---

name: skill-architecture description: Comprehensive guide for creating effective Claude Code skills with security best practices, CLI-specific features, and structural patterns. Use when creating skills, needing security guidance, understanding skill architecture, or learning best practices.

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):

Copy/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):

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

For distribution (validates AND creates zip):

Copy/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

Copyskill-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)

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