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

When to Use This Skill

Use this skill when:

Creating new Claude Code skills from scratch
Learning skill YAML frontmatter and structure requirements
Validating skill file format and portability
Understanding progressive disclosure patterns for skills

FIRST: TodoWrite Task Templates

MANDATORY: Select and load the appropriate template into TodoWrite before any skill work.

For detailed context on each step, see Skill Creation Process (Detailed Tutorial) below.

Template A: Create New Skill

1. Gather requirements (ask user for functionality, examples, triggers)
2. Identify reusable resources (scripts, references, assets needed)
3. Run init script to create skill directory structure
4. Create bundled resources first (scripts/, references/, assets/)
5. Write SKILL.md with YAML frontmatter (name, description with triggers)
6. Add TodoWrite task templates section to SKILL.md
7. Add Post-Change Checklist section to SKILL.md
8. Validate with quick_validate.py
9. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
10. Test skill on real example
11. Register skill in project CLAUDE.md
12. Verify against Skill Quality Checklist below

Template B: Update Existing Skill

1. Read current SKILL.md and understand structure
2. Identify what needs changing (triggers, workflow, resources)
3. Make targeted changes to SKILL.md
4. Update any affected references/ or scripts/
5. Validate with quick_validate.py
6. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. Test updated behavior
8. Update project CLAUDE.md if description changed
9. Verify against Skill Quality Checklist below

Template C: Add Resources to Skill

1. Read current SKILL.md to understand skill purpose
2. Determine resource type (script, reference, or asset)
3. Create resource in appropriate directory
4. Update SKILL.md to document new resource
5. Validate with quick_validate.py
6. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
7. Test resource integration
8. Verify against Skill Quality Checklist below

Template D: Convert to Self-Evolving Skill

1. Read current SKILL.md structure
2. Add TodoWrite Task Templates section (scenario-specific)
3. Add Post-Change Checklist section
4. Create references/evolution-log.md (reverse chronological - newest on top)
5. Create references/config-reference.md (if skill manages external config)
6. Update description with self-evolution triggers
7. Validate with quick_validate.py
8. Validate links (relative paths only): bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
9. Test self-documentation on sample change
10. Verify against Skill Quality Checklist below

Template E: Troubleshoot Skill Not Triggering

1. Check YAML frontmatter syntax (no colons in description)
2. Verify trigger keywords in description match user queries
3. Check skill location (~/.claude/skills/ or project .claude/skills/)
4. Validate with quick_validate.py for errors
5. Validate links: bun run plugins/plugin-dev/scripts/validate-links.ts <skill-path>
6. Test with explicit trigger phrase
7. Document findings in skill if new issue discovered
8. Verify against Skill Quality Checklist below

Skill Quality Checklist

After ANY skill work, verify:

YAML frontmatter valid (name lowercase-hyphen, description has triggers)
Description includes WHEN to use (trigger keywords)
TodoWrite templates cover all common scenarios
Post-Change Checklist included for self-maintenance
Final template step references this checklist
Project CLAUDE.md updated if new/renamed skill
Validated with quick_validate.py
All markdown links use relative paths (plugin-portable)
No broken internal links (validate-links.ts passes)
No unsafe path patterns (see Path Patterns):
- No hardcoded
```
/Users/<user>
```
  or
```
/home/<user>
```
  (use
```
$HOME
```
  )
- No hardcoded
```
/tmp
```
  in Python (use
```
tempfile.TemporaryDirectory
```
  )
- No hardcoded binary paths (use
```
command -v
```
  or PATH)
Bash compatibility verified (see Bash Compatibility):
- All bash code blocks wrapped with
```
/usr/bin/env bash << 'NAME_EOF'
```
- No
```
declare -A
```
  (associative arrays) - use parallel indexed arrays
- No
```
grep -P
```
  (Perl regex) - use
```
grep -E
```
  with awk
- No
```
\!=
```
  in conditionals - use
```
!=
```
  directly
- Heredoc EOF marker is descriptive (e.g.,
```
PREFLIGHT_EOF
```
  )

Post-Change Checklist (Self-Maintenance)

After modifying THIS skill (skill-architecture):

Templates and 6 Steps tutorial remain aligned
Skill Quality Checklist reflects current best practices
All referenced files in references/ exist
Append changes to evolution-log.md
Update user's CLAUDE.md if triggers changed

Continuous Improvement (Proactive Self-Evolution)

CRITICAL: Skills must actively evolve. Don't wait for explicit requests—upgrade skills when insights emerge.

During Every Skill Execution

Watch for these improvement signals:

Signal	Example	Action
Friction	Step feels awkward or unclear	Rewrite for clarity
Missing edge case	Workflow fails on valid input	Add handling + document
Better pattern	Discover more elegant approach	Update + log why
User confusion	Same question asked repeatedly	Add clarification or FAQ
Tool evolution	Underlying tool gains features	Update to leverage them
Repeated manual steps	Same code written each time	Create script in `scripts/`

Immediate Update Protocol

When improvement opportunity identified:

Pause current task (briefly)
Make the improvement to SKILL.md or resources
Log in evolution-log.md (one-liner is fine for small changes)
Resume original task

Rationale: Small immediate updates compound. Waiting means insights are forgotten. 30 seconds now saves 5 minutes later.

What NOT to Update Immediately

Major structural changes (discuss with user first)
Changes that would break in-progress work
Speculative improvements without concrete evidence

Self-Reflection Trigger

After completing any skill-assisted task, ask:

"Did anything about this skill feel suboptimal? If I encountered this again, what would help?"

If answer exists → update the skill NOW.

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

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

Skill Creation Process (Detailed Tutorial)

Note: Use TodoWrite templates above for execution. This section provides detailed context for each phase.

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 init script from plugin-dev:

bash

uv run plugins/plugin-dev/scripts/skill-creator/init_skill.py <skill-name> --path <target-path>

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 must include:

What is the purpose? (few sentences)
When should it be used? (trigger keywords in description)
How should Claude use bundled resources?
TodoWrite Task Templates - Pre-defined todos for common scenarios
Post-Change Checklist - Self-maintenance verification

Start with resources (

scripts/

references/

assets/

), then update SKILL.md

Step 5: Validate the Skill

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

bash

uv run plugins/plugin-dev/scripts/skill-creator/quick_validate.py <path/to/skill-folder>

For distribution (validates AND creates zip):

bash

uv run plugins/plugin-dev/scripts/skill-creator/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: Register and Iterate

Register skill in project CLAUDE.md (Workspace Skills section)
Use skill on real tasks
Notice struggles/inefficiencies
Update SKILL.md or resources
Test again
Verify against Skill Quality Checklist above

Skill Anatomy

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

YAML Frontmatter (Required)

yaml

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

Field	Rules
`name`	Lowercase, hyphens, numbers. Max 64 chars. Unique.
`description`	WHAT it does + WHEN to use. Max 1024 chars (CLI) / 200 (API). Include triggers!
`allowed-tools`	CLI-only. Comma-separated list restricts tools. Optional.

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)

YAML Description Pitfalls:

Pitfall	Problem	Fix
Multiline syntax	`>` or `\|` not supported	Single line only
Colons in text	`CRITICAL: requires` breaks YAML	Use `CRITICAL - requires`
Quoted strings	Valid but not idiomatic	Unquoted preferred (match anthropics/skills)

yaml

# ❌ BREAKS - colon parsed as YAML key:value
description: ...CRITICAL: requires flag

# ✅ WORKS - dash instead of colon
description: ...CRITICAL - requires flag

Validation: GitHub renders frontmatter - invalid YAML shows red error banner.

Progressive Disclosure (3 Levels)

Skills use progressive loading to manage context efficiently:

Metadata (name + description) - Always in context (~100 words)
SKILL.md body - When skill triggers (<5k words)
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:

Workflow Pattern - Sequential multi-step procedures
Task Pattern - Specific, bounded tasks
Reference Pattern - Knowledge repository
Capabilities Pattern - Tool integrations

User Conventions Integration

This skill follows common user conventions:

Absolute paths: Always use full paths (terminal 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 when appropriate

Marketplace Scripts

See Scripts Reference for marketplace script usage.

Reference Documentation

For detailed information, see:

Structural Patterns - 4 skill architecture patterns
Workflow Patterns - Workflow skill implementation 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
Path Patterns - Safe/unsafe path references (known bugs documented)
Validation Reference - Quality checklist
SYNC-TRACKING - Marketplace version tracking
Evolution Log - This skill's change history

Troubleshooting

Issue	Cause	Solution
Skill not triggering	Missing trigger keywords	Add trigger phrases to description field
YAML parse error	Colon in description	Replace colons with dashes in description
Skill not found	Wrong location	Place in `~/.claude/skills/` or project `.claude/skills/`
validate script fails	Invalid frontmatter	Check name format (lowercase-hyphen only)
Resources not loading	Wrong path in SKILL.md	Use relative paths from skill directory
Script execution fails	Missing shebang or permissions	Add `#!/usr/bin/env python3` and `chmod +x`
allowed-tools ignored	API skill (not CLI)	allowed-tools only works in CLI skills
Description too long	Over 1024 chars	Shorten description, move details to SKILL.md body

skill-architecture

NPX Install

Tags

SKILL.md Content

Skill Architecture

When to Use This Skill

FIRST: TodoWrite Task Templates

Template A: Create New Skill

Template B: Update Existing Skill

Template C: Add Resources to Skill

Template D: Convert to Self-Evolving Skill

Template E: Troubleshoot Skill Not Triggering

Skill Quality Checklist

Post-Change Checklist (Self-Maintenance)

Continuous Improvement (Proactive Self-Evolution)

During Every Skill Execution

Immediate Update Protocol

What NOT to Update Immediately

Self-Reflection Trigger

About Skills

What Skills Provide

Skill Creation Process (Detailed Tutorial)

Step 1: Understanding the Skill with Concrete Examples

Step 2: Planning Reusable Contents

Step 3: Initialize the Skill

Step 4: Edit the Skill

Step 5: Validate the Skill

Step 6: Register and Iterate

Skill Anatomy

YAML Frontmatter (Required)

Progressive Disclosure (3 Levels)

Bundled Resources

CLI-Specific Features

Structural Patterns

User Conventions Integration

Marketplace Scripts

Reference Documentation

Troubleshooting