Create Agent Skills

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.

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

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

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

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

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

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

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

1. Create a new skill - Build a skill from scratch
2. Update an existing skill - Modify or improve an existing skill
3. 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

1. 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)"

2. After user enters number, read that skill's SKILL.md

3. Ask what they want to change/improve using AskUserQuestion or direct question

4. Proceed with modifications

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

Do NOT ask about things that are obvious from context.

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.

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

Options:

1. Proceed to building - I have enough context to build the skill
2. Ask more questions - There are more details to clarify
3. 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

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:

1. Yes, research first - Fetch 2024-2025 documentation for accurate implementation
2. 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.

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.

Core principles: references/core-principles.md

• XML structure (consistency, parseability, Claude performance)
• Conciseness (context window is shared)
• Degrees of freedom (matching specificity to task fragility)
• Model testing (Haiku vs Sonnet vs Opus)

Skill structure: references/skill-structure.md

• XML structure requirements
• Naming conventions
• Writing effective descriptions
• Progressive disclosure patterns
• File organization

Workflows and validation: references/workflows-and-validation.md

• Complex workflows with checklists
• Feedback loops (validate → fix → repeat)
• Plan-validate-execute pattern

Common patterns: references/common-patterns.md

• Template patterns
• Examples patterns
• Consistent terminology
• Anti-patterns to avoid

Executable code: references/executable-code.md

• When to use utility scripts
• Error handling in scripts
• Package dependencies
• MCP tool references

API security: references/api-security.md

• Preventing credentials from appearing in chat
• Using the secure API wrapper
• Adding new services and operations
• Credential storage patterns

Iteration and testing: references/iteration-and-testing.md

• Evaluation-driven development
• Claude A/B development pattern
• Observing how Claude navigates Skills
• XML structure validation during testing

Prompting fundamentals:

• references/be-clear-and-direct.md
• references/use-xml-tags.md

• Valid YAML frontmatter with descriptive name and comprehensive description
• Pure XML structure with no markdown headings in body
• Required tags: objective, quick_start, success_criteria
• Conditional tags appropriate to complexity level
• Progressive disclosure (SKILL.md < 500 lines, details in reference files)
• Clear, concise instructions that assume Claude is smart
• Real-world testing and iteration based on observed behavior
• Lightweight slash command wrapper for discoverability