Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

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-skill

About 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 (use create-skill-test)
  • Creating custom agents (use the agents/ directory pattern)

Inputs

InputRequiredDescription
Skill nameYesLowercase, alphanumeric, hyphens only (e.g., code-review, ci-triage)
DescriptionYesWhat the skill does and when agents should use it (1-1024 chars)
PurposeYesOne paragraph describing the outcome
Workflow stepsRecommendedNumbered 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 for the full evidence.

DoInstead of
Encode the decision the model would otherwise get wrongRestating API signatures it already reproduces
"When A, do B, never C, verify D" tablesLists of plausible alternatives
A concrete output contract (exact command, verdict line, findings table)"Consider…", "you may want to…"
Scale output structure to input sizeA 12-section dashboard for an 8-test suite
Stop-conditions that prevent over-applyingActing before measuring, rewriting working code
Instructing the agent to discover repo pathsMarking discoverable paths as required inputs
Reporting restore/build/test failures truthfullyClaiming success after a failed command
Verifying load-bearing API claims by compiling or probingTrusting 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

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
Read the complete source ↗