create-agent-skills - Claude Skills

name	create-agent-skills
description	Expert guidance for creating, writing, building, and refining Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving existing skills, or understanding skill structure, progressive disclosure, workflows, validation patterns, and XML formatting.

Agent Skills are modular, filesystem-based capabilities that provide domain-specific expertise through progressive disclosure. This Skill teaches you how to create effective Skills that Claude can discover and use successfully.

Skills are organized prompts that get loaded on-demand. All prompting best practices apply, with an emphasis on pure XML structure for consistent parsing and efficient token usage.

1. **Identify the reusable pattern**: What context or procedural knowledge would be useful for similar future tasks? 2. **Create directory and SKILL.md**: - Directory name: Follow verb-noun convention: `create-*`, `manage-*`, `setup-*`, `generate-*` (see [references/skill-structure.md](references/skill-structure.md) for details) - YAML frontmatter: - `name`: Matches directory name, lowercase-with-hyphens, max 64 chars - `description`: What it does AND when to use it (third person, max 1024 chars) 3. **If skill requires API credentials**: See [references/api-security.md](references/api-security.md) for credential setup 4. **Write concise instructions**: Assume Claude is smart. Only add context Claude doesn't have. Use pure XML structure. 5. **Test with real usage**: Iterate based on observations. ```yaml --- name: process-pdfs description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. --- Extract text and tables from PDF files, fill forms, and merge documents using Python libraries. Extract text with pdfplumber:

import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

**Form filling**: See [forms.md](forms.md) **API reference**: See [reference.md](reference.md) ``` All skills must have these tags:

<objective> - What the skill does and why it matters
<quick_start> - Immediate, actionable guidance
<success_criteria> or <when_successful> - How to know it worked

Based on skill complexity, add these tags as needed:

<context> - Background/situational information
<workflow> or <process> - Step-by-step procedures
<advanced_features> - Deep-dive topics (progressive disclosure)
<validation> - How to verify outputs
<examples> - Multi-shot learning
<anti_patterns> - Common mistakes to avoid
<security_checklist> - Non-negotiable security patterns
<testing> - Testing workflows
<common_patterns> - Code examples and recipes
<reference_guides> or <detailed_references> - Links to reference files

**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links). Single domain, straightforward tasks: Use required tags only.

Example: Text extraction, file format conversion, simple API calls

Multiple patterns, some complexity: Use required tags + workflow/examples as needed.

Example: Document processing with multiple steps, API integration with configuration

Multiple domains, security concerns, API integrations: Use required tags + conditional tags as appropriate.

Example: Payment processing, authentication systems, multi-step workflows with validation

Don't over-engineer simple skills. Don't under-specify complex skills. Match tag selection to actual complexity and user needs. **Adaptive Requirements Gathering**: Before building, gather requirements through intelligent questioning that infers obvious details and asks about genuine gaps. **BEFORE doing anything else**, check if context was provided.

IF no context provided (user just invoked the skill without describing what to build): → IMMEDIATELY use AskUserQuestion with these exact options:

Create a new skill - Build a skill from scratch
Update an existing skill - Modify or improve an existing skill
Get guidance on skill design - Help me think through what kind of skill I need

DO NOT ask "what would you like to build?" in plain text. USE the AskUserQuestion tool.

Routing after selection:

"Create new" → proceed to adaptive intake below
"Update existing" → enumerate existing skills as numbered list (see below), then gather requirements for changes
"Guidance" → help user clarify needs before building

When "Update existing" is selected:

List all skills in chat as numbered list (DO NOT use AskUserQuestion - there may be many skills):
- Glob for ~/.claude/skills/*/SKILL.md
- Present as numbered list in chat:
```
Available skills:
1. create-agent-skills
2. generate-natal-chart
3. manage-stripe
...
```
- Ask: "Which skill would you like to update? (enter number)"
After user enters number, read that skill's SKILL.md
Ask what they want to change/improve using AskUserQuestion or direct question
Proceed with modifications

IF context was provided (user said "build a skill for X"): → Skip this gate. Proceed directly to adaptive intake.

Parse the initial description: - What's explicitly stated (operations, services, outputs) - What can be inferred without asking (skill type, complexity, obvious patterns) - What's genuinely unclear or ambiguous (scope boundaries, edge cases, specific behaviors)

Do NOT ask about things that are obvious from context.

Use AskUserQuestion to ask 2-4 domain-specific questions based on actual gaps.

Question generation guidance:

Scope questions: "What specific operations?" not "What should it do?"
Complexity questions: "Should this handle [specific edge case]?" based on domain knowledge
Output questions: "What should the user see/get when successful?"
Boundary questions: "Should this also handle [related thing] or stay focused?"

Avoid:

Questions answerable from the initial description
Generic questions that apply to all skills
Yes/no questions when options would be more helpful
Obvious questions like "what should it be called?" when the name is clear

Each question option should include a description explaining the implications of that choice.

After receiving answers, present decision gate using AskUserQuestion:

Question: "Ready to proceed with building, or would you like me to ask more questions?"

Options:

Proceed to building - I have enough context to build the skill
Ask more questions - There are more details to clarify
Let me add details - I want to provide additional context

If "Ask more questions" selected → loop back to generate_questions with refined focus If "Let me add details" → receive additional context, then re-evaluate If "Proceed" → continue to research_trigger, then step_1

Detect if the skill involves external APIs or services.

When external service detected, ask using AskUserQuestion: "This involves [service name] API. Would you like me to research current endpoints and patterns before building?"

Options:

Yes, research first - Fetch 2024-2025 documentation for accurate implementation
No, proceed with general patterns - Use common patterns without specific API research

If research requested:

Use Context7 MCP to fetch current library documentation
Or use WebSearch for recent API documentation
Focus on 2024-2025 sources for current patterns
Store findings for use in content generation

Research findings flow into step_1 analysis and inform code examples in later steps.

**Analyze the domain**: Understand what the skill needs to teach and its complexity level. Incorporate gathered requirements and any research findings from step_0. **Select XML tags**: Choose required tags + conditional tags based on intelligence rules. **Write YAML frontmatter**: Validate name (matches directory, verb-noun convention) and description (third person, includes triggers). **Structure content in pure XML**: No markdown headings in body. Use semantic XML tags for all sections. **Apply progressive disclosure**: Keep SKILL.md under 500 lines. Split detailed content into reference files. **Validate structure**: - YAML frontmatter valid - Required tags present (objective, quick_start, success_criteria) - No markdown headings in body - Proper XML nesting and closing tags - Reference files linked appropriately **Test with real usage**: Observe Claude using the skill. Iterate based on actual behavior, not assumptions. **Create slash command wrapper**: Create a lightweight slash command that invokes the skill.

Location: ~/.claude/commands/{skill-name}.md

Template:

---
description: {Brief description of what the skill does}
argument-hint: [{argument description}]
allowed-tools: Skill({skill-name})
---

<objective>
Delegate {task} to the {skill-name} skill for: $ARGUMENTS

This routes to specialized skill containing patterns, best practices, and workflows.
</objective>

<process>
1. Use Skill tool to invoke {skill-name} skill
2. Pass user's request: $ARGUMENTS
3. Let skill handle workflow
</process>

<success_criteria>
- Skill successfully invoked
- Arguments passed correctly to skill
</success_criteria>

The slash command's only job is routing—all expertise lives in the skill.

```yaml --- name: skill-name-here description: What it does and when to use it (third person, specific triggers) --- ``` See [references/skill-structure.md](references/skill-structure.md) for complete validation rules and naming conventions. - Reusable patterns across multiple tasks - Domain knowledge that doesn't change frequently - Complex workflows that benefit from structured guidance - Reference materials (schemas, APIs, libraries) - Validation scripts and quality checks One-off tasks that won't be reused Explicit user-triggered workflows that run with fresh context For deeper topics, see reference files:

Core principles: references/core-principles.md