create-skill
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).
dotnet · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add dotnet/skills --skill create-skillAbout this 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(usecreate-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 FORclause 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: trueto 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 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:
- Purpose: One paragraph describing the outcome
- When to Use: Bullet list of appropriate scenarios
- When Not to Use: Boundaries and exclusions
- Inputs: Table of required and optional inputs
- Workflow: Numbered steps with checkpoints
- Validation: How to confirm the skill worked correctly
- 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
Step 8: Update CODEOWNERS
Add entries in .github/CODEOWNERS for the new skill and its test directory:
/plugins/<plugin>/skills/<skill-name>/ @owner-team
/tests/<plugin>/<skill-name>/ @owner-team
Match the owner pattern used by sibling skills in the same plugin.
Step 9: Validate the skill
- Confirm frontmatter fields are valid
- Ensure SKILL.md is under 500 lines
- Check that file ref