| name | creating-skills |
| description | Create, validate, and iteratively improve agent skills that follow Anthropic's best practices. Use this skill whenever someone wants to create a new skill, improve an existing skill, write a SKILL.md, set up a skill directory structure, or needs guidance on skill authoring patterns. Also triggers when users mention "custom instructions", "agent skill", "skill template", or want to codify a workflow into a reusable skill. This skill enforces a create-validate-improve loop that produces production-ready skills passing code review on the first submission.
|
Creating Skills — Author, Validate, Improve
This skill guides you through producing agent skills that follow Anthropic's official best practices. It enforces an iterative loop: draft → validate → improve → re-validate, until the skill meets all quality criteria.
When to read additional files
The Core Loop
Every skill goes through this cycle. Your job is to figure out where the user is and help them progress.
┌──────────────┐
│ 0. DISCOVER │ Scan for existing skills that overlap
│ │
└──────┬───────┘
▼
┌──────────────┐
│ 1. CAPTURE │ Understand what the skill should do
│ INTENT │
└──────┬───────┘
▼
┌──────────────┐
│ 2. DRAFT │ Write SKILL.md + directory structure
│ │
└──────┬───────┘
▼
┌──────────────┐
│ 3. VALIDATE │ Run checklist against the draft
│ │ (read references/validation-rules.md)
└──────┬───────┘
▼
┌──────────────┐ ┌──────────────┐
│ 4. TEST │---->│ 5. IMPROVE │
│ (optional) │ │ based on │
│ │<----│ findings │
└──────┬───────┘ └──────────────┘
▼ │
Passes all? │
User happy? <------------┘
▼
┌──────────────┐
│ 6. PACKAGE │ Final structure, ready for repo
└──────────────┘
Step 0: Discover Existing Skills
Before creating a new skill — or even before capturing intent in detail — scan for existing skills that might already cover the need.
How to scan
-
Find all SKILL.md files across the skill directories declared in the repo's copilot-instructions.md (or scan recursively from the repo root):
find . -name "SKILL.md" -type f
-
Extract frontmatter from each — just the name and description fields. Build a compact inventory:
migrating-wcf-to-corewcf | Migrates WCF services from .NET Framework to CoreWCF...
managing-target-frameworks | Manages target frameworks in .NET project files...
-
Compare the proposed skill against the inventory on three dimensions:
- Name conflict — exact match is a hard block; similar names (e.g.,
processing-pdfs vs pdf-processing) are a warning
- Description overlap — high keyword overlap between descriptions signals a likely duplicate
- Trigger phrase collision — if two skills mention the same file types, APIs, or user phrases in their descriptions, they will compete for the same queries
-
Report findings before proceeding:
- If an existing skill fully covers the need → recommend using it instead
- If an existing skill partially covers the need → recommend extending it or referencing it
- If overlap is minor → note it and proceed with the new skill
- If no overlap → proceed
When improving an existing skill
Still run the scan — the improved skill's new description or triggers might now overlap with another skill that didn't overlap before. Check specifically for trigger phrase collisions after editing descriptions.
Skip conditions
Skip this step only when the user explicitly says "I know there's no overlap" or when the skill name was provided by the user as a deliberate choice.
Step 1: Capture Intent
Start by understanding what the user wants. If the current conversation already contains a workflow they want to capture ("turn this into a skill"), extract answers from context first.
Gather these essentials (ask only what's missing):
- What should this skill enable Claude to do? — The core capability.
- When should it trigger? — User phrases, file types, contexts.
- What's the expected output? — File types, formats, or behaviors.
- What does "good" look like? — Success criteria the user cares about.
- Does it need scripts or just instructions? — Pure markdown vs. code-assisted.
- Who is the audience? — Other developers? Non-technical users? Both?
Don't over-interview. If you have enough to draft, draft. You can refine later.
Step 2: Draft the Skill
Read templates/SKILL-TEMPLATE.md for the starting structure.
The frontmatter includes name, description, and an optional metadata block with traits (pipe-separated technology tags) and discovery (e.g., lazy for on-demand loading). See the template for the exact format.
Key principles while drafting
Conciseness is non-negotiable. Claude is already smart. Only add context Claude doesn't already have. For every paragraph, ask: "Does this justify its token cost?"
Match freedom to fragility:
- High freedom (guidelines) → when multiple approaches are valid
- Medium freedom (pseudocode) → when a preferred pattern exists
- Low freedom (exact scripts) → when operations are fragile or order matters
Write descriptions in third person. The description is injected into a system prompt. "Processes Excel files and generates reports" — not "I can help you" or "You can use this to."
Make descriptions pushy. Skills tend to under-trigger. Include both what the skill does AND when to use it, with specific trigger phrases and contexts.
Use language-neutral terminology. Say "project file" instead of .csproj when the context applies to any .NET project type (C#, VB.NET, F#). Only use specific extensions when the context is truly language-specific.
Explain the why. Instead of rigid MUSTs in all caps, explain reasoning. Claude responds better to understanding intent than to blunt force rules.
Directory structure
skill-name/
├── SKILL.md # Required. Under 500 lines.
├── references/ # Optional. Detailed docs loaded on demand.
│ ├── some-domain.md
│ └── another-domain.md
├── scripts/ # Optional. Executable utilities.
│ ├── validate.py
│ └── helper.sh
├── templates/ # Optional. Output templates.
└── assets/ # Optional. Fonts, icons, images.
Naming rules
Format: lowercase letters, numbers, hyphens only. Max 64 chars. No reserved words ("anthropic", "claude").
Choosing a good name — lead with a gerund verb:
The name should answer "what does this skill do?" in 2-5 hyphenated words. Start with a gerund (verb ending in -ing) that describes the primary action:
| Action type | Pattern | Examples |
|---|
| Migration (A→B) | migrating-{source}-to-{target} | migrating-wcf-to-corewcf, migrating-newtonsoft-to-system-text-json |
| Migration (general) | migrating-{what} | migrating-aspnet-identity, migrating-global-asax |
| Conversion | converting-to-{target} | converting-to-sdk-style |
| Management | managing-{what} | managing-target-frameworks, managing-package-references |
| Integration | integrating-{what} | integrating-autofac-with-dotnet |
| Modification | modifying-{what} | modifying-project-properties |
Naming anti-patterns:
- ❌ Noun-only:
msmq-migration → ✅ migrating-to-msmq-messaging
- ❌ Redundant suffix with gerund:
migrating-aspnet-identity-migration → ✅ migrating-aspnet-identity
- ❌ Vague:
helper, utils, tools, data, files
- ❌ Technology dump:
system-security-cryptography-migration → ✅ migrating-cryptography-namespaces
Exception — scenario and system skills: Gerund naming applies to production and agent skills. Scenario skills (discovery: scenario) are multi-stage workflow orchestrators — use noun-form names that describe the workflow: dotnet-version-upgrade, not upgrading-dotnet-version. System skills (discovery: system) are infrastructure capabilities loaded by the system prompt — use noun-form names that describe the concern: state-management, plan-generation, task-execution.
Description rules
- Max 1024 characters. Must be non-empty.
- No XML tags.
- Third person only.
- Include trigger phrases and contexts.
- Be specific: "Extract text and tables from PDF files, fill forms, merge documents" — not "Helps with documents."
- No cross-references in descriptions. Descriptions are for triggering — mentioning another skill's name pollutes keyword matching and wastes the character budget. Put cross-references in the skill body instead (e.g., a
> **Related skill:** callout in the Overview section).
- This project uses custom
metadata frontmatter fields (traits, discovery) for skill routing. Preserve these when improving existing skills. Include them when creating new skills.
Step 3: Validate
This is where most skill authoring fails — people skip validation entirely.
Read references/validation-rules.md and run every check against the draft. Start with the automated validator to catch structural issues:
# Windows (PowerShell)
.\scripts\validate_skill.ps1 .\path\to\skill
bash scripts/validate_skill.sh ./path/to/skill
Both scripts check the same rules and produce the same scorecard. The automated checks cover structure, frontmatter, line counts, paths, and reference depth. The full validation also includes subjective checks that need human review:
- Structure — Frontmatter, file organization, line counts
- Content quality — Conciseness, freedom calibration, terminology consistency
- Description effectiveness — Trigger coverage, specificity, third person
- Progressive disclosure — Reference depth, file organization
- Code quality (if applicable) — Error handling, no magic numbers, dependency listing
- Anti-patterns — Windows paths, too many options, time-sensitive info, nested references
Present findings to the user as a scorecard:
Skill Validation Report: [skill-name]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Structure — Frontmatter valid, 127 lines
✅ Description — Specific, third-person, trigger phrases included
⚠️ Conciseness — Lines 45-62 explain what Claude already knows
❌ Progressive disc. — References nested 2 levels deep (max 1)
✅ Terminology — Consistent throughout
⚠️ Code quality — scripts/helper.py has unexplained TIMEOUT=47
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Result: 2 issues to fix before this passes review
Step 4: Test (when applicable)
Testing is optional but recommended for skills with objectively verifiable outputs.
Create 2-3 realistic test prompts — things a real user would actually say. Not abstract placeholders, but concrete requests with file names, context, and detail. Share them with the user for confirmation.
For each test prompt:
- Follow the skill's instructions yourself to complete the task
- Check if the output matches the skill's stated success criteria
- Note where instructions were unclear, missing, or led you astray
If the skill has scripts, actually run them and verify they work.
Step 5: Improve
Based on validation findings and test results:
- Generalize, don't overfit. If a test case revealed a gap, fix it in a way that handles the general class of problems, not just that specific case.
- Keep it lean. Remove anything that isn't pulling its weight. If a section didn't help during testing, cut it.
- Explain the why. If you find yourself writing "ALWAYS" or "NEVER" in caps, reframe it as reasoning. "Because XML validation is fragile and errors cascade, validate after every edit" beats "ALWAYS VALIDATE."
- Bundle repeated work. If you found yourself writing the same helper code across test cases, that's a script the skill should bundle.
After improving, go back to Step 3 (Validate) and run the checklist again. Repeat until clean.
Step 6: Package
Final checks before the skill is ready:
- All validation rules pass
- SKILL.md is under 500 lines
- Reference files longer than 100 lines have a table of contents
- All file paths use forward slashes
- Scripts have explicit error handling
- No time-sensitive information (or it's in an "old patterns" section)
- Dependencies are listed with install commands
Present the final directory structure to the user and confirm it's ready for their repo.
Special Scenarios
Scenario skills with time-sensitive data
Scenario skills that reference technology versions, release status, or support lifecycle dates should include a ## Current Facts section. This section provides authoritative grounding data that the agent uses instead of potentially stale training knowledge.
Convention:
- Section must be named exactly
## Current Facts
- Place it near the top of the SKILL.md (after the scenario overview)
- Include a
<!-- Last updated: YYYY-MM-DD --> comment for freshness tracking
- Content should be a table of verifiable facts (versions, dates, status)
- No opinions or recommendations — just facts
- Add a staleness check callout for items that may change (e.g., versions marked "Preview")
Example:
## Current Facts
<!-- Last updated: 2025-11-12 -->
| Version | Status | Support Level | End of Life |
|---------|--------|---------------|-------------|
| .NET 10 | GA | LTS | 2028-11-14 |
| .NET 9 | GA | STS | 2026-11-10 |
| .NET 11 | Preview | — | 2030-11-12 (projected) |
> **Staleness check:** If the user asks about a version listed as **Preview** above,
> verify its current status using an internet search tool before answering —
> it may have shipped since this data was last updated.
The system prompt's Freshness Rule directs the agent to consult this section before answering version/lifecycle questions from training memory.
"Turn this conversation into a skill"
The user has been working through a problem and wants to capture the workflow. Extract from the conversation:
- Tools and commands used
- Sequence of steps taken
- Corrections the user made (these are especially valuable — they reveal edge cases)
- Input/output formats observed
- Domain knowledge the user provided
Draft a skill from this, then validate normally.
"Improve this existing skill"
Copy the skill to a writable location. Read it carefully. Run validation. Present the scorecard. Fix issues iteratively. Preserve the original name.
"I just want a quick skill, skip the process"
Respect the user's time. Draft it, run a quick mental validation for the most critical rules (description quality, line count, no anti-patterns), mention any red flags, and deliver. You can always improve later.
Communicating with the User
Pay attention to the user's technical level. Some users building skills are experienced engineers; others are discovering what a terminal is for the first time.
- Default to clear, jargon-lite language
- If the user shows strong technical signals, match their level
- Briefly explain terms like "frontmatter", "progressive disclosure", or "YAML" if there's any doubt
- Never condescend — just be clear
