/create-skill

name: create-skill
description: Scaffolds new agent skills for the dotnet/skills repository. Use when creating a new skill, generating SKILL.md files, writing a skill description that the runtime will actually route to, or setting up skill directory structures. Handles frontmatter generation, section templates, and validation guidance. Do not use for fixing a skill that already fails its evaluation (use improve-skill-quality) or for writing eval.yaml (use create-skill-test).

Create Skill

This skill helps you scaffold new agent skills that conform to the Agent Skills specification and the dotnet/skills repository conventions.

When to Use

• Creating a new skill from scratch
• Generating a SKILL.md file with proper frontmatter
• Setting up the skill directory structure with optional folders
• Ensuring compliance with agentskills.io specification

When Not to Use

• Modifying existing skills (edit directly instead)
• Diagnosing or fixing a skill that fails its evaluation (use `improve-skill-quality`)
• Writing the skill's `eval.yaml` (use `create-skill-test`)
• Creating custom agents (use the agents/ directory pattern)

Inputs

| Input | Required | Description | |-------|----------|-------------| | Skill name | Yes | Lowercase, alphanumeric, hyphens only (e.g., `code-review`, `ci-triage`) | | Description | Yes | What the skill does and when agents should use it (1-1024 chars) | | Purpose | Yes | One paragraph describing the outcome | | Workflow steps | Recommended | Numbered steps the agent should follow |

Workflow

Step 1: Validate the skill name

Ensure the name:

• Contains only lowercase letters, numbers, and hyphens
• Does not start or end with a hyphen
• Does not contain consecutive hyphens
• Is between 1-64 characters

Step 2: Write the description — it is the router

The `description` is the **only** text the runtime sees when deciding whether to load the skill. A perfect body behind a weak description never runs.

---
name: <skill-name>
description: <what it does>. USE FOR: <symptoms, error codes, artifact names, quoted user requests>. DO NOT USE FOR: <nearby-but-wrong intents, with the skill that owns them>.
---

• Lead with an action verb and use the user's own words: symptoms, error codes (`CS1501`,

`MSTEST0014`), artifact names (`.testsettings`, `binlog`), and requests phrased as a developer would type them.

• Partition against sibling skills on the **real discriminator**, not the topic. "Does the

abstraction already exist?" separates two skills; "testing" does not. Add the matching exclusion to **both** siblings.

• Claim the ambiguous words that would otherwise route to a sibling. If prompts say "review my

tests" and a sibling owns "review", say so explicitly.

• Check every `DO NOT USE FOR` clause against the scenarios the skill exists to serve — an

exclusion like "already on v3" can lock out the post-upgrade fixes that are the skill's purpose.

• Budget: 1,024 characters per description, and the whole plugin's rendered skill menu is also

budgeted. A helper skill users should never invoke directly can set `disable-model-invocation: true` to free menu space while staying invocable by name.

Step 3: Write for delta over the baseline model

Every skill is scored head-to-head against the same model with **no skill loaded**. Content the model already produces unaided is worth zero; content that makes it slower or more hedged is worth less than zero. See [improve-skill-quality/references/writing-for-baseline-delta.md](../improve-skill-quality/references/writing-for-baseline-delta.md) for the full evidence.

| Do | Instead of | |----|------------| | Encode the decision the model would otherwise get wrong | Restating API signatures it already reproduces | | "When A, do B, never C, verify D" tables | Lists of plausible alternatives | | A concrete output contract (exact command, verdict line, findings table) | "Consider…", "you may want to…" | | Scale output structure to input size | A 12-section dashboard for an 8-test suite | | Stop-conditions that prevent over-applying | Acting before measuring, rewriting working code | | Instructing the agent to discover repo paths | Marking discoverable paths as required inputs | | Reporting restore/build/test failures truthfully | Claiming success after a failed command | | Verifying load-bearing API claims by compiling or probing | Trusting a source read | | Gating rare or expensive paths behind `references/` | One large SKILL.md carrying every path |

Do not over-correct: a skilled answer shorter and less actionable than the baseline's still loses.

Step 4: Create the skill directory

plugins/<plugin>/skills/<skill-name>/
└── SKILL.md

Step 5: Generate SKILL.md with frontmatter

Create the file with the frontmatter drafted in Step 2.

Step 6: Add body content sections

Include these recommended sections:

1. **Purpose**: One paragraph describing the outcome 2. **When to Use**: Bullet list of appropriate scenarios 3. **When Not to Use**: Boundaries and exclusions 4. **Inputs**: Table of required and optional inputs 5. **Workflow**: Numbered steps with checkpoints 6. **Validation**: How to confirm the skill worked correctly 7. **Common Pitfalls**: Known traps and how to avoid them

Step 7: Add optional directories (if needed)

plugins/<plugin>/skills/<skill-name>/
├── SKILL.md
├── scripts/       # Executable code agents can run
├── references/    # Additional documentation loaded on demand
└── assets/        # Templates, images, data files

Reference bundled files with paths relative to the directory that contains `SKILL.md`, such as `references/details.md` or `scripts/validate.ps1`. Do not tell the agent to search for the skill's installation directory. If a missing bundled file reduces the result quality, allow one listing of the known bundled-file directory and require the agent to report the reduced coverage.

Step 8: Update CODEOWNERS

Add entr