Loading
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 u
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add dotnet/skills --skill create-skill -a cursor -y
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).
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).
This skill helps you scaffold new agent skills that conform to the Agent Skills specification and the dotnet/skills repository conventions.
improve-skill-quality)eval.yaml (use create-skill-test)| 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 |
Ensure the name:
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>.
---
CS1501,
MSTEST0014), artifact names (.testsettings, binlog), and requests phrased as a developer
would type them.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.disable-model-invocation: true to free menu space.
It remains a readable resource, not a skill the model can invoke by name. Consumers read the
catalog or its bundled files directly using the supplied catalog path (the staged path in native
evaluation). Resolve bundled-file paths relative to the catalog, not the project workspace.Vector<T> or <Import>. Spell it out in words ("generic Vector type",
"Import element"); skill-validator check fails on it.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.
plugins/<plugin>/skills/<skill-name>/
└── SKILL.md
Create the file with the frontmatter drafted in Step 2.
Include these recommended sections:
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.
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.
dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/<plugin>A skill without an eval.yaml has no evidence that it improves on the baseline. Use
create-skill-test to add one in the same pull request, and size it for statistical power — an eval
below five distinct stimuli can never return a passing verdict.
The exception is a helper/reference catalog with disable-model-invocation: true: the model cannot
invoke it, so a direct eval compares two identical arms. Cover it through the outcome evals of the
consumer skills that read its resources instead.
Use this template when creating a new skill:
---
name: <skill-name>
description: <1-1024 char description of what the skill does and when to use it>
---
# <Skill Title>
<One paragraph describing the skill's purpose and outcome.>
## When to Use
- <Scenario 1>
- <Scenario 2>
## When Not to Use
- <Exclusion 1>
- <Exclusion 2>
## Inputs
| Input | Required | Description |
|-------|----------|-------------|
| <input-name> | Yes/No | <description> |
## Workflow
### Step 1: <Action>
<Instructions for this step>
### Step 2: <Action>
<Instructions for this step>
## Validation
- [ ] <Verification step 1>
- [ ] <Verification step 2>
## Common Pitfalls
| Pitfall | Solution |
|---------|----------|
| <Problem> | <How to avoid or fix> |
After creating a skill, verify:
Vector<T>)SKILL.md.github/CODEOWNERS has entries for the new skill and its test directoryeval.yaml exists and clears the distinct-stimulus floor (or the skill is disable-model-invocation: true and covered through its consumers)| Pitfall | Solution |
|---|---|
| Name contains uppercase letters | Use only lowercase: code-review not Code-Review |
| Description is vague | Include what it does AND when to use it |
| Instructions are ambiguous | Use numbered steps with concrete actions |
| Missing validation steps | Add checkpoints that verify success |
| SKILL.md too long | Move detailed content to references/ files |
| Hardcoded environment assumptions | Document requirements in compatibility field |
| Missing CODEOWNERS entry | Add entries for both /plugins/<plugin>/skills/<skill-name>/ and /tests/<plugin>/<skill-name>/ matching sibling skills' owner pattern |
| Skill restates what the model already knows | Cut it; a skill is scored as a delta over the unskilled model |
| Discoverable paths listed as required inputs | Tell the agent to discover them, or it will stop and ask the user |
| Description partitioned by topic against a sibling | Partition on the real discriminator and exclude on both sides |
| Exclusion clause blocks the skill's own use cases | Re-read every "do not use for" clause against real workflow phases |
| Skill added without an eval | Add eval.yaml in the same PR; unevaluated skills carry no evidence |
eval.yaml