--- name: Skill Scaffolder slug: skill-scaffolder category: AI Engineering description: Skill Scaffolder creates new agent skills that conform to the Agent Skills specification and dotnet/skills conventions, generating SKILL.md frontmatter, section templates, and validation guidance. Use it when setting up a new skill directory or writing a description that the runtime will route to. github: "https://github.com/dotnet/skills/tree/main/.agents/skills/create-skill" language: "C#" stars: 5165 forks: 384 install: "npx degit https://github.com/dotnet/skills/tree/main/.agents/skills/create-skill ~/.claude/skills/create-skill" installs_to: ~/.claude/skills/create-skill source_path: .agents/skills/create-skill/SKILL.md collection_size: 25 category_size: 2451 collection_url: "https://dirskills.com/collections/dotnet/skills" added: 2026-08-16T07:00:27.939Z last_synced: 2026-08-16T07:00:27.939Z canonical_url: "https://dirskills.com/skills/skill-scaffolder" --- # Skill Scaffolder Skill Scaffolder creates new agent skills that conform to the Agent Skills specification and dotnet/skills conventions, generating SKILL.md frontmatter, section templates, and validation guidance. Use it when setting up a new skill directory or writing a description that the runtime will route to. **Install:** ```bash npx degit https://github.com/dotnet/skills/tree/main/.agents/skills/create-skill ~/.claude/skills/create-skill ``` ## README # 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. ```yaml --- name: description: . USE FOR: . DO NOT USE FOR: . --- ``` - 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//skills// └── 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//skills// ├── 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//skills// @owner-team /tests/// @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 references use relative paths - Verify instructions are actionable and specific - Run `dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- check --plugin ./plugins/` ### Step 10: Add the eval 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 counted trials can never return a passing verdict. The exception is a helper skill with `disable-model-invocation: true`: the model cannot self-activate it, so an activation-graded eval compares two identical arms. Cover it through the evals of the skills that load it instead. ## SKILL.md Template Use this template when creating a new skill: ```markdown --- name: description: <1-1024 char description of what the skill does and when to use it> --- # ## When to Use - - ## When Not to Use - - ## Inputs | Input | Required | Description | |-------|----------|-------------| | | Yes/No | | ## Workflow ### Step 1: ### Step 2: ## Validation - [ ] - [ ] ## Common Pitfalls | Pitfall | Solution | |---------|----------| | | | ``` ## Validation Checklist After creating a skill, verify: - [ ] Skill name matches directory name exactly - [ ] Skill name is lowercase with hyphens only - [ ] Description is non-empty and under 1024 characters - [ ] SKILL.md body is under 500 lines - [ ] Instructions are specific and actionable - [ ] Workflow has numbered steps with clear checkpoints - [ ] Validation section exists with observable success criteria - [ ] No secrets, tokens, or internal URLs included - [ ] `.github/CODEOWNERS` has entries for the new skill and its test directory - [ ] The description names concrete triggers and excludes the nearest sibling skills - [ ] Every section changes a decision the unskilled model would otherwise get wrong - [ ] The skill states when **not** to act, and what a truthful failure report looks like - [ ] An `eval.yaml` exists and clears the trial floor (or the skill is `disable-model-invocation: true` and covered through its consumers) ## Common Pitfalls | 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//skills//` and `/tests///` 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 | ## References - [Agent Skills Specification](https://agentskills.io/specification) - [Repository README](../../../README.md) - [Contributing Guidelines](../../../CONTRIBUTING.md) - [create-skill-test](../create-skill-test/SKILL.md) — authoring the skill's `eval.yaml` - [improve-skill-quality](../improve-skill-quality/SKILL.md) — fixing a skill that loses to its baseline