Skill Architecture

Comprehensive guide for creating effective Claude Code skills following Anthropic's official standards with emphasis on security, CLI-specific features, and progressive disclosure architecture.

⚠️ Scope: Claude Code CLI Agent Skills (~/.claude/skills/), not Claude.ai API skills

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains—transforming Claude from general-purpose to specialized agent with procedural knowledge no model fully possesses.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, assets for complex/repetitive tasks

Skill Creation Process (6 Steps)

Step 1: Understanding the Skill with Concrete Examples

Clearly understand concrete examples of how the skill will be used. Ask users:

• "What functionality should this skill support?"
• "Can you give examples of how it would be used?"
• "What would trigger this skill?"

Skip only when usage patterns are already clearly understood.

Step 2: Planning Reusable Contents

Analyze each example to identify what resources would be helpful:

Example 1 - PDF Editor:

• Rotating PDFs requires rewriting code each time
• → Create scripts/rotate_pdf.py

Example 2 - Frontend Builder:

• Webapps need same HTML/React boilerplate
• → Create assets/hello-world/ template

Example 3 - BigQuery:

• Queries require rediscovering table schemas
• → Create references/schema.md

Step 3: Initialize the Skill

Run the marketplace init script (don't copy, use from marketplace):

/Users/terryli/.claude/plugins/marketplaces/anthropic-agent-skills/skill-creator/scripts/init_skill.py <skill-name> --path ~/.claude/skills/

Creates: skill directory + SKILL.md template + example resource directories

Step 4: Edit the Skill

Writing Style: Imperative/infinitive form (verb-first), not second person

• ✅ "To accomplish X, do Y"
• ❌ "You should do X"

SKILL.md should answer:

1. What is the purpose? (few sentences)
2. When should it be used?
3. How should Claude use bundled resources?

Start with resources (scripts/, references/, assets/), then update SKILL.md

Step 5: Validate the Skill

For local development (validation only, no zip creation):

/Users/terryli/.claude/plugins/marketplaces/anthropic-agent-skills/skill-creator/scripts/quick_validate.py <path/to/skill-folder>

For distribution (validates AND creates zip):

/Users/terryli/.claude/plugins/marketplaces/anthropic-agent-skills/skill-creator/scripts/package_skill.py <path/to/skill-folder>

Validates: YAML frontmatter, naming, description, file organization

Note: Use quick_validate.py for most workflows. Only use package_skill.py when actually distributing the skill to others.

Step 6: Iterate

1. Use skill on real tasks
2. Notice struggles/inefficiencies
3. Update SKILL.md or resources
4. Test again

Skill Anatomy

skill-name/
├── SKILL.md           # Required: YAML frontmatter + instructions
├── scripts/           # Optional: Executable code (Python/Bash)
├── references/        # Optional: Documentation loaded as needed
└── assets/            # Optional: Files used in output

YAML Frontmatter (Required)

---
name: skill-name-here
description: What this does and when to use it (max 1024 chars for CLI)
allowed-tools: Read, Grep, Bash # Optional, CLI-only feature
---

Field Requirements:

Good vs Bad Descriptions:

✅ Good: "Extract text and tables from PDFs, fill forms, merge documents. Use when working with PDF files or when user mentions forms, contracts, document processing."

❌ Bad: "Helps with documents" (too vague, no triggers)

Progressive Disclosure (3 Levels)

Skills use progressive loading to manage context efficiently:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - When skill triggers (<5k words)
3. Bundled resources - As needed by Claude (unlimited*)

*Scripts can execute without reading into context.

Bundled Resources

Skills can include scripts/, references/, and assets/ directories. See Progressive Disclosure for detailed guidance on when to use each.

CLI-Specific Features

CLI skills support allowed-tools restriction for security. See Security Practices for details.

Structural Patterns

See Structural Patterns for detailed guidance on:

1. Workflow Pattern - Sequential multi-step procedures
2. Task Pattern - Specific, bounded tasks
3. Reference Pattern - Knowledge repository
4. Capabilities Pattern - Tool integrations

User Conventions Integration

This skill follows Terry's conventions from ~/.claude/CLAUDE.md:

• Absolute paths: Always use /Users/terryli/... (iTerm2 Cmd+click compatible)
• Unix-only: macOS, Linux (no Windows support)
• Python: uv run script.py with PEP 723 inline dependencies
• Planning: OpenAPI 3.1.1 specs in /Users/terryli/.claude/specifications/

Marketplace Scripts

See Scripts Reference for marketplace script usage.

Reference Documentation

For detailed information, see:

• Structural Patterns - 4 skill architecture patterns
• Progressive Disclosure - Context management patterns
• Creation Workflow - Step-by-step process
• Scripts Reference - Marketplace script usage
• Security Practices - Threats and defenses (CVE references)
• Token Efficiency - Context optimization
• Advanced Topics - CLI vs API, composition, bugs
• Validation Reference - Quality checklist
• SYNC-TRACKING - Marketplace version tracking