Skill Creator

Skill Creator

Use this skill to create and improve portable Agent Skills that load correctly in GitHub Copilot, VS Code, GitHub Copilot CLI, and other skills-compatible agents. The output is a skill folder with a valid SKILL.md, optional bundled resources, and a validation pass before delivery.

When to use

Use this skill when the user wants to:

• Create a new skill.
• Turn a conversation or repeated workflow into a reusable skill.
• Audit, repair, or modernize an existing skill folder.
• Diagnose why a skill does not appear or does not trigger.
• Optimize a skill description for better automatic loading.
• Add references, scripts, assets, test prompts, or review artifacts to a skill.

Required skill format

Every skill folder follows this shape:

skill-name/
  SKILL.md
  references/   optional, on-demand Markdown references
  scripts/      optional, runnable helpers
  assets/       optional, templates or static resources

The directory name must match the name field in SKILL.md. The name uses lowercase letters, numbers, and hyphens only. Avoid slashes, colons, dots, namespaces, spaces, and uppercase letters because invalid names can prevent discovery.

SKILL.md starts with YAML frontmatter on line 1:

---
name: skill-name
description: What the skill does and when to use it, with concrete trigger phrases.
---

# Skill instructions

Required frontmatter keys:

• name: must match the folder.
• description: must explain both what the skill does and when to use it. Keep it at or below 1024 characters.

Supported optional keys in this repository:

• argument-hint
• license
• user-invocable
• disable-model-invocation
• allowed-tools
• metadata
• tags

Do not use unsupported top-level keys such as context, compatibility, authors, category, or version. Put annotations such as compatibility, author, and version under metadata when needed.

Workflow

1. Clarify intent

Capture the smallest useful version of the skill before writing files. Ask or infer:

• What capability should the skill provide?
• What user requests should trigger it?
• What should the skill produce?
• Does it need references, scripts, assets, or all three?
• Does it need objective tests, human review, or both?
• Is it a project skill under .github/skills/ or a personal skill under ~/.copilot/skills/?

If the user asks to convert an existing conversation into a skill, extract the workflow, mistakes, corrections, commands, output formats, and validation steps from that conversation before asking new questions.

2. Choose the package shape

Keep SKILL.md focused on the core workflow and progressive disclosure. Move long domain knowledge into references/. Put repeatable deterministic work into scripts/. Put templates or examples into assets/.

Good split:

• SKILL.md: overview, when to use, workflow, output requirements, validation.
• references/*.md: detailed rules, examples, schemas, style guides.
• scripts/*: validators, renderers, converters, reproducible helpers.
• assets/*: templates, sample input, HTML review pages, icons, fixtures.

Every file referenced from SKILL.md must exist.

3. Write or update SKILL.md

Use clear imperative instructions. Explain why key steps matter instead of relying on rigid all-caps rules. Include:

• What the skill helps accomplish.
• When it should be used.
• Step-by-step workflow.
• Inputs and outputs.
• Validation commands.
• Pointers to bundled references, scripts, and assets.

Write the description for discovery. Include trigger phrases and near-synonyms a real user would type. Do not hide trigger guidance only in the body because the description is the primary discovery surface.

4. Add tests or review artifacts

For skills with objective output, write 3 to 5 realistic test prompts and expected checks. Store them in evals/evals.json if the user wants an evaluation loop. For subjective skills, provide a human review checklist instead of forcing weak quantitative assertions.

Use references/schemas.md for optional eval JSON shapes.

For trigger-description review, use assets/eval_review.html to review should-trigger and should-not-trigger prompts with the user.

5. Validate before delivery

Run the bundled validator on the skill folder:

python3 .github/skills/skill-creator/scripts/validate_skill.py .github/skills/<skill-name>

Also run repository gates when working in this repository:

python3 harness/github-copilot/scripts/validate_primitives.py --strict
python3 harness/github-copilot/scripts/generate_catalog.py --check

Fix every error before claiming the skill is ready.

6. Improve an existing skill

When updating a skill:

• Preserve the folder name and name field unless the user explicitly asks to rename it.
• Read the current skill before editing.
• Work with existing references, scripts, and assets instead of replacing the package blindly.
• Keep unrelated changes out.
• Validate the updated skill folder.

Validation checklist

Before delivery, confirm:

• SKILL.md starts with frontmatter on line 1.
• name exists and matches the folder.
• description exists, is specific, and is at most 1024 characters.
• No unsupported frontmatter keys are present.
• No sandbox paths or hard platform leaks are present.
• No broken local file references exist.
• Every bundled script compiles or has a documented runtime requirement.
• Documentation is in English.
• User-facing copy writes "GitHub Copilot" in full.

Bundled resources

• references/schemas.md: optional JSON schemas for evals, grading, benchmark summaries, trigger eval sets, and feedback.
• assets/eval_review.html: self-contained browser UI for reviewing trigger eval queries.
• eval-viewer/generate_review.py: standard-library review viewer for comparing generated outputs and collecting feedback.
• scripts/validate_skill.py: deterministic validator for Agent Skill package structure and repository conventions.

Notes for portability

Prefer portable Agent Skills concepts over one-agent-only mechanics. This skill targets GitHub Copilot in VS Code, GitHub Copilot CLI, and GitHub Copilot cloud agent. If a requested workflow depends on a tool that is not available in the current environment, document the dependency and provide a graceful fallback.