Skill Builder

Skill Builder

Purpose

Creates production-ready Agent Skills following the official specifications and best practices.

When I Activate

I automatically load when you mention:

• "build a skill" or "create a skill"
• "generate a skill" or "make a skill"
• "design a skill" or "new skill"

Authoritative References (Read These First)

Before creating any skill, read the current versions of these docs:

1. Agent Skills Specification (the open standard): https://agentskills.io/specification 2. Skill Authoring Best Practices (Anthropic): https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices 3. Claude Code Skills Documentation (Claude Code extensions): https://docs.claude.com/en/docs/claude-code/skills 4. Example Skills (reference implementations): https://github.com/anthropics/skills

These are the source of truth. If anything in this skill contradicts those docs, the official docs win.

What I Do

Create skills in 5 steps:

1. Clarify → Define purpose, scope, activation keywords 2. Design → Plan structure, decide on progressive disclosure 3. Generate → Create SKILL.md with proper frontmatter and body 4. Validate → Check against spec and best practices 5. Test → Verify activation and behavior

Frontmatter (Agent Skills Spec)

Only two fields are required:

---
name: my-skill
description: What this skill does and when to use it. Include specific keywords for discovery.
---

Optional fields: license, compatibility, metadata, allowed-tools.

Claude Code adds: disable-model-invocation, user-invocable, model, context, agent, hooks, argument-hint.

Do NOT use: version (use metadata.version), auto_activates, priority_score, source_urls, evaluation_criteria, invokes, philosophy, maturity — none of these are recognized by any runtime.

Key Best Practices

From the official best practices:

Conciseness

• Claude is already smart. Only add context it doesn't have.
• Challenge every paragraph: "Does this justify its token cost?"
• SKILL.md body under 500 lines.

Description Quality

• Write in third person ("Processes Excel files", not "I help you")
• Include both what the skill does AND when to use it
• Include specific trigger keywords for discovery
• Max 1024 characters

Progressive Disclosure

• Metadata loaded at startup (name + description only)
• SKILL.md loaded when skill activates
• Supporting files loaded only when needed
• Keep references one level deep from SKILL.md

Degrees of Freedom

• High freedom: Multiple valid approaches, context-dependent
• Medium freedom: Preferred pattern exists, some variation OK
• Low freedom: Fragile operations, exact sequence required

No Time-Sensitive Content

• Never write "as of today", "recently added", "new in v3.0"
• Use an "old patterns" section for historical context if needed

Feedback Loops

• Run validator → fix errors → repeat
• Include verification steps for critical operations

Validation Checklist

✅ Frontmatter: name and description present and valid ✅ Name: Lowercase, hyphens only, 1-64 chars, matches directory name ✅ Description: 1-1024 chars, third person, includes trigger keywords ✅ Body: Under 500 lines ✅ References: One level deep from SKILL.md ✅ No stale content: No temporal references ✅ Consistent terminology: One term per concept throughout ✅ Tested: Works with at least 3 representative prompts

Supporting Files

• reference.md: Detailed patterns, architecture, validation rules
• examples.md: Skill creation workflows and examples

Skill Builder Examples

Comprehensive examples of creating Claude Code skills using the skill-builder.

Last Updated: 2025-11-15

---

Basic Examples

Example 1: Simple Auto-Discovery Skill

User Request: "I need a skill for validating JSON schemas"

Command:

/amplihack:skill-builder json-validator skill "Validates JSON data against schemas with detailed error reporting"

Expected Output:

.claude/skills/json-validator/
└── SKILL.md

Generated SKILL.md:

---
name: json-validator
description: Validates JSON data against schemas with detailed error reporting. Use for JSON validation, schema checking, or data quality assurance.
---

# JSON Validator

## Purpose

Validates JSON data against predefined schemas and provides detailed error reports.

## When I Activate

I automatically load when you mention:

- "validate JSON" or "check JSON schema"
- "JSON validation" or "schema validation"
- "verify JSON structure"

## What I Do

1. Accept JSON data and schema definition
2. Parse and validate structure
3. Check types, required fields, constraints
4. Generate detailed error reports
5. Suggest fixes for validation failures

## Usage Example

User: "Validate this JSON against the user schema" Skill: _activates automatically_ "I'll validate that JSON for you..."

Example 2: Command-Based Skill

User Request: "Create a command for analyzing test coverage"

Command:

/amplihack:skill-builder test-coverage command "Analyzes test coverage gaps and suggests improvements"

Expected Output:

.claude/commands/amplihack/test-coverage.md

Generated File Structure:

---
description: Analyzes test coverage gaps and suggests improvements
argument-hint: [target-path]
---

# Test Coverage Analyzer

## Usage

`/amplihack:test-coverage [target-path]`

## Purpose

Identifies gaps in test coverage and recommends additional test cases.

## EXECUTION INSTRUCTIONS FOR CLAUDE

[Step-by-step workflow...]

Example 3: Agent Skill

User Request: "Build an agent for dependency analysis"

Command:

/amplihack:skill-builder dependency-analyzer agent "Analyzes project dependencies and detects version conflicts"

Expected Output:

.claude/agents/amplihack/specialized/dependency-analyzer.md:

---
role: dependency-analyzer
description: Analyzes project dependencies, detects version conflicts, and identifies security vulnerabilities across npm, pip, cargo, and other package managers
---

# Dependency Analyzer Agent

## Role

Specialized agent for comprehensive dependency analysis and conflict resolution.

## When to Invoke

- Dependency conflicts blocking development
- Security audit of dependencies required
- Version compatibility analysis needed
- License compliance checking
- Before major version upgrades

## Capabilities

1. **Conflict Detection**: Identifies version mismatches and incompatible requirements
2. **Security Scanning**: Checks for known CVEs and vulnerabilities
3. **License Analysis**: Validates license compatibility and compliance
4. **Update Recommendations**: Suggests safe upgrade paths
5. **Transitive Analysis**: Maps complete dependency trees

## Analysis Process

### Step 1: Discover Dependencies

Scan project for dependency files:

- package.json, package-lock.json (npm)
- requirements.txt, Pipfile, pyproject.toml (Python)
- Cargo.toml, Cargo.lock (Rust)
- go.mod, go.sum (Go)

### Step 2: Build Dependency Graph

Map direct and transitive dependencies with version constraints.

### Step 3: Detect Conflicts

Identify:

- Version mismatches between direct dependencies
- Incompatible transitive dependencies
- Circular dependencies
- Missing peer dependencies

### Step 4: Security Audit

Check each dependency against:

- npm audit / pip-audit / cargo audit
- Known CVE databases
- GitHub security advisories

### Step 5: Generate Report

Provide:

- Conflict summary with resolution suggestions
- Security vulnerabilities with severity ratings
- License compatibility matrix
- Safe upgrade path recommendations

## Output Format

**Conflict Report**:

CONFLICTS FOUND:

• package-a@1.0 requires foo@^2.0
• package-b@2.0 requires foo@^3.0

RESOLUTION: Upgrade package-a to 2.0 (compatible with foo@^3.0)

**Security Report**:

VULNERABILITIES:

• axios@0.21.0: CVE-2021-3749 (HIGH)

Fix: Upgrade to axios@0.21.2+

## Integration

Works with:
- ci-diagnostic-workflow (pre-push dependency checks)
- security agent (vulnerability assessment)
- pre-commit-diagnostic (local validation)

Example 4: Scenario Tool Skill

User Request: "Create a production tool for code review automation"

Command:

/amplihack:skill-builder code-reviewer scenario "Automated code review with security and quality checks"

Expected Output:

.claude/scenarios/code-reviewer/code_reviewer.py:

#!/usr/bin/env python3
"""Automated code review with security and quality checks."""

import argparse
import sys
from pathlib import Path
from dataclasses import dataclass
from typing import List


@dataclass
class ReviewResult:
    """Results from reviewing a single file."""

    file_path: Path
    issues: List[str]
    security_concerns: List[str]
    quality_score: float


def review_file(file_path: Path) -> ReviewResult:
    """Review a single file for security and quality issues."""
    issues = []
    security_concerns = []

    content = file_path.read_text()

    # Security checks
    if "eval(" in content:
        security_concerns.append("Code injection risk: eval() detected")
    if "exec(" in content:
        security_concerns.append("Code execution risk: exec() detected")

    # Quality checks
    lines = content.split("\n")
    if len(lines) > 500:
        issues.append(f"File too large: {len(lines)} lines (recommend < 500)")

    # Calculate quality score
    quality_score = 100.0
    quality_score -= len(issues) * 5
    quality_score -= len(security_concerns) * 10

    return ReviewResult(
        file_path=file_path,
        issues=issues,
        security_concerns=security_concerns,
        quality_score=max(0.0, quality_score),
    )


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Automated code review with security and quality checks"
    )
    parser.add_argument("target", help="File or directory to review")
    parser.add_argument(
        "--format", choices=["text", "json"], default="text", help="Output format"
    )
    args = parser.parse_args()

    target = Path(args.target)
    if not target.exists():
        print(f"Error: {target} not found", file=sys.stderr)
        sys.exit(1)

    # Collect files to review
    files = [target] if target.is_file() else list(target.rglob("*.py"))

    # Review each file
    results = [review_file(f) for f in files]

    # Display results
    for result in results:
        print(f"\n{result.file_path}")
        print(f"Quality Score: {result.quality_score:.1f}/100")
        if result.security_concerns:
            print("Security Concerns:")
            for concern in result.security_concerns:
                print(f"  - {concern}")
        if result.issues:
            print("Issues:")
            for issue in result.issues:
                print(f"  - {issue}")


if __name__ == "__main__":
    main()

.claude/scenarios/code-reviewer/README.md:

````markdown

Code Reviewer

Automated code review with security and quality checks.

Features

• Security vulnerability detection (eval, exec, SQL injection patterns)
• Code quality metrics (file size, complexity, style)
• Multiple output formats (text, JSON)
• Recursive directory scanning

Installation

# From amplihack repository root
pip install -e .

````

Usage

# Review single file
python .claude/scenarios/code-reviewer/code_reviewer.py file.py

# Review directory
python .claude/scenarios/code-reviewer/code_reviewer.py ./src/

# JSON output
python .claude/scenarios/code-reviewer/code_reviewer.py ./src/ --format json

Output

./src/module.py
Quality Score: 95.0/100
Issues:
  - Function too complex: calculate_metrics (20 branches)

Integration

Add to Makefile:

review-code:
	python .claude/scenarios/code-reviewer/code_reviewer.py $(TARGET)

---

## Advanced Examples

### Example 5: Multi-File Skill with Scripts

**User Request**: "Build a skill for financial analysis with calculations"

**Natural Language** (skill auto-activates):

User: "I need to build a skill that calculates financial ratios like ROE and P/E" skill-builder: _activates automatically_ "I'll help you create that financial analysis skill..."

**Generated Structure**:

.claude/skills/financial-analyzer/ ├── SKILL.md # Core instructions (<5K tokens) ├── reference.md # Detailed formulas and methodologies ├── examples.md # Sample analyses └── scripts/ ├── calculate.py # Ratio calculations └── validate.py # Input validation

````

SKILL.md (Progressive Disclosure):

---
name: financial-analyzer
description: Calculate and interpret financial ratios (ROE, P/E, debt-to-equity, current ratio) against industry benchmarks. Use for financial statements, balance sheets, or income statement analysis.
---

# Financial Analyzer

## Purpose

Calculates key financial ratios and interprets them against industry benchmarks.

## When I Activate

- "analyze financial statements"
- "calculate ROE" or "calculate P/E ratio"
- "financial ratio analysis"

## What I Do

1. Accept financial data (income statement, balance sheet)
2. Calculate ratios using scripts/calculate.py
3. Compare against industry benchmarks
4. Interpret results with context
5. Generate formatted analysis report

## Instructions

For detailed formulas and methodologies, see [reference.md](./reference.md).
For usage examples, see [examples.md](./examples.md).

[Core workflow steps...]

Example 6: Read-Only Skill with Security

User Request: "Create a secure skill that only reads code, never modifies"

Command:

/amplihack:skill-builder code-auditor skill "Audits code for security vulnerabilities without making changes"

Generated SKILL.md:

---
name: code-auditor
description: Audits code for security vulnerabilities without making changes. Read-only security analysis for OWASP top 10, injection flaws, and authentication issues.
allowed-tools: Read, Grep, Glob # Security restriction
---

# Code Auditor

## Purpose

Security-focused code auditing without modification capabilities.

## Security Features

- **Read-Only**: Cannot modify code (allowed-tools restriction)
- **No Execute**: Cannot run code
- **Safe Analysis**: Only inspection and reporting

[Rest of skill...]

---

Validation Examples

Valid Skill Names

✅ data-transformer ✅ json-validator ✅ api-client-v2 ✅ pdf-form-filler ✅ code-reviewer

Invalid Skill Names

❌ DataTransformer (not kebab-case) ❌ data_transformer (underscore not allowed) ❌ dt (too short, min 3 chars) ❌ data transformer (space not allowed) ❌ ThisIsWayTooLongOfANameForASkillAndShouldBeRejected (>64 chars)

Valid Descriptions

✅ "Transforms data between JSON, YAML, and XML formats with validation" ✅ "Analyzes test coverage and identifies gaps in unit, integration, and E2E tests" ✅ "Generates Mermaid diagrams from text descriptions for flowcharts and sequence diagrams"

Invalid Descriptions

❌ "Transform" (too short, no context) ❌ "Does stuff" (too vague, no specificity) ❌ "A really amazing and wonderful tool that does absolutely everything you could possibly imagine and more beyond your wildest dreams..." (too long, >1024 chars)

---

Real-World Skill Building Session

Session: Creating a Data Transformation Skill

Step 1: User Request

User: "I want to create a skill that transforms data between different formats"

Step 2: Skill Builder Activates (Auto-Discovery)

skill-builder: "I'll help you create that data transformation skill.
               Let me clarify the requirements..."

Step 3: Requirements Clarification (prompt-writer)

Questions asked:
- Which formats to support? (JSON, YAML, XML, CSV)
- Should it validate after transformation?
- Any specific transformation rules?
- Target complexity level?

Step 4: Architecture Design (architect)

Design decisions:
- Skill type: skill (for auto-discovery)
- Multi-file structure (SKILL.md + scripts/)
- Token budget: 4,500 tokens (within limit)
- Supporting scripts for deterministic parsing

Step 5: Skill Generation (builder)

Generated files:
.claude/skills/data-transformer/
├── SKILL.md           (core instructions)
└── scripts/
    ├── parse.py       (format parsing)
    └── transform.py   (transformation logic)

Step 6: Validation (reviewer)

Validation results:
- YAML frontmatter: ✅ Valid
- Token budget: ✅ 4,500 tokens (under 5K limit)
- Description quality: ✅ Keyword-rich for discovery
- Philosophy compliance: ✅ 92% (>85% threshold)
- Zero-BS check: ✅ No stubs or placeholders

Step 7: Completion Report

✅ Skill created successfully!

**Location**: .claude/skills/data-transformer/SKILL.md
**Type**: Claude Code Skill (auto-discovery)
**Token Budget**: 4,500 / 5,000 tokens (90%)
**Philosophy Score**: 92/100

**Next Steps**:
1. Restart Claude Code to load new skill
2. Test with: "Transform this JSON to YAML"
3. Skill should activate automatically
4. Verify transformation works correctly

**Usage**:
- Natural: "Transform this JSON to YAML"
- Explicit: Use /amplihack:skill-builder to invoke directly

---

Testing Examples

Test 1: Activation Testing

Objective: Verify skill activates on expected prompts

Test Prompts:

1. "Build a skill for PDF processing"
   → skill-builder should activate

2. "Create a new skill that analyzes logs"
   → skill-builder should activate

3. "Generate a skill for API testing"
   → skill-builder should activate

4. "Help me with my code"
   → skill-builder should NOT activate (irrelevant)

Test 2: Validation Testing

Objective: Ensure validation catches errors

Test Cases:

# Test invalid name
/amplihack:skill-builder DataTransformer skill "Description"
Expected: Error - "Name must be kebab-case"

# Test invalid type
/amplihack:skill-builder data-tool invalid "Description"
Expected: Error - "Type must be: skill, agent, command, scenario"

# Test short description
/amplihack:skill-builder data-tool skill "Short"
Expected: Warning - "Description too short (min 10 chars)"

# Test long description
/amplihack:skill-builder data-tool skill "..."  # 1500 chars
Expected: Error - "Description exceeds 1,024 character limit"

Test 3: File Creation Testing

Objective: Verify correct file paths and structures

Test Cases:

# Skill type → creates directory with SKILL.md
/amplihack:skill-builder test-skill skill "Test skill"
Expected: .claude/skills/test-skill/SKILL.md

# Agent type → creates .md file directly
/amplihack:skill-builder test-agent agent "Test agent"
Expected: .claude/agents/amplihack/specialized/test-agent.md

# Command type → creates .md file in commands
/amplihack:skill-builder test-cmd command "Test command"
Expected: .claude/commands/amplihack/test-cmd.md

# Scenario type → creates directory with README.md
/amplihack:skill-builder test-scenario scenario "Test scenario"
Expected: .claude/scenarios/test-scenario/README.md

---

Common Patterns from Community

Pattern: Gerund Naming (metaskills/skill-builder)

Convention: Use gerund form (verb-ing) for skill names

✅ Preferred: processing-data, analyzing-code, generating-reports ❌ Avoid: data-processor, code-analyzer, report-generator

Rationale: Emphasizes action/capability over noun/object

Pattern: CLI-First Approach (metaskills/skill-builder)

Preference: Use CLI tools over programmatic APIs

✅ Preferred: gh, aws cli, npm, jq, curl ❌ Avoid: Python SDKs, custom API wrappers

Rationale: Simpler, more portable, easier to debug

Pattern: Intention-Revealing File Names

Convention: File names should clearly indicate purpose

✅ Good: calculate_financial_ratios.py, validate_json_schema.py ❌ Bad: utils.py, helpers.py, functions.py

---

Edge Cases and Gotchas

Edge Case 1: Name Collisions

Problem: Skill name already exists

Detection:

def check_name_conflict(skill_name, skill_type):
    paths = {
        "skill": f".claude/skills/{skill_name}/SKILL.md",
        "agent": f".claude/agents/amplihack/specialized/{skill_name}.md",
        "command": f".claude/commands/amplihack/{skill_name}.md",
        "scenario": f".claude/scenarios/{skill_name}/README.md"
    }
    target_path = paths[skill_type]
    if Path(target_path).exists():
        return f"Conflict: {skill_type} '{skill_name}' already exists"
    return None

Solution: Prompt for different name or versioning (v2, v3, etc.)

Edge Case 2: Token Budget Creep

Problem: Skill grows beyond budget over time

Detection: Regular health checks

Prevention:

• Monitor token count in CI
• Warn at 80% budget usage
• Auto-suggest reference.md split at 4,000 tokens
• Track version-to-version growth

Edge Case 3: Description Too Generic

Problem: Skill never activates (poor description)

Detection: Usage analytics show 0 activations

Fix: Enhance description with specific keywords:

# Before (too generic)
description: Analyzes data

# After (specific)
description: Analyzes CSV, Excel, and JSON data for patterns, outliers, and statistical insights. Use for data analysis, quality checks, or exploratory data analysis.

---

Comparison: Skills vs Other Amplihack Constructs

Skills vs Agents

Skills:

• Auto-discover based on description
• Token-efficient (load on-demand)
• Can restrict tools via allowed-tools
• Emphasis on user intent matching

Agents:

• Explicitly invoked by orchestrator
• Always loaded in agent system
• Full tool access
• Emphasis on specialization

When to Use Each:

• Skill: User-facing capabilities, auto-activation desired
• Agent: Internal orchestration, explicit delegation needed

Skills vs Commands

Skills:

• Natural language invocation
• Auto-discovery
• Conversational interface

Commands:

• Slash command syntax
• Explicit parameters
• Structured invocation

When to Use Each:

• Skill: Conversational workflow, auto-activation
• Command: Power users, precise control, clear parameters

Skills vs Scenarios

Skills:

• Lightweight documentation
• Fast activation
• Single SKILL.md (or multi-file)

Scenarios:

• Full production tools
• Complete with tests, docs, Makefile
• Python/JS implementations

When to Use Each:

• Skill: Quick capabilities, documentation-driven
• Scenario: Complex tools, code implementations, mature features

---

Integration Examples

Example: Skill + Command Dual Interface

Like the skill-builder itself:

As Command (explicit):

/amplihack:skill-builder my-skill skill "Description"

As Skill (auto-discovery):

User: "Help me build a new skill for parsing logs"
skill-builder: *activates automatically*

Benefits:

• Power users get control (command)
• Casual users get convenience (skill auto-activation)
• Same underlying workflow

Example: Skill + Agent Coordination

Skill loads → Delegates to agents:

User: "Build a skill for API testing"

skill-builder skill activates
  ↓
Orchestrates agents:
  1. prompt-writer: Clarifies API testing requirements
  2. architect: Designs skill structure
  3. builder: Generates SKILL.md
  4. reviewer: Validates philosophy compliance
  5. tester: Creates test cases
  ↓
Delivers complete skill in .claude/skills/api-tester/

---

Troubleshooting

Issue: Skill Never Activates

Symptoms: Created skill doesn't load when expected

Diagnosis:

# Check 1: Description keywords
skill_md = Path(".claude/skills/my-skill/SKILL.md").read_text()
frontmatter = parse_yaml_frontmatter(skill_md)
print(f"Description: {frontmatter['description']}")
# Does it include keywords users would say?

# Check 2: Claude Code restarted
# Skills load at startup - must restart after adding skill

# Check 3: YAML valid
import yaml
yaml.safe_load(frontmatter_text)  # Should not error

Solutions:

1. Enhance description with trigger keywords 2. Restart Claude Code 3. Fix YAML syntax errors 4. Check file location (~/.amplihack/.claude/skills/skill-name/SKILL.md)

Issue: Token Budget Exceeded

Symptoms: Warning or error about token count

Diagnosis:

import tiktoken

encoding = tiktoken.encoding_for_model("claude-sonnet-4-5")
skill_content = Path(".claude/skills/my-skill/SKILL.md").read_text()
tokens = len(encoding.encode(skill_content))
print(f"Token count: {tokens}")

Solutions:

1. Move details to reference.md 2. Extract examples to examples.md 3. Move code to scripts/ 4. Remove redundant explanations 5. Use bullet points over paragraphs

Issue: Skill Conflicts

Symptoms: Multiple skills activate for same request

Diagnosis: Descriptions overlap (both match user intent)

Solutions:

1. Make descriptions more specific 2. Add domain constraints 3. Use disableModelInvocation: true for one 4. Consolidate into single skill

---

Best Practices from metaskills/skill-builder

Source: https://github.com/metaskills/skill-builder

Opinionated Naming: Gerunds

# Preferred (action-oriented)
processing-data
analyzing-code
generating-reports

# Less preferred (object-oriented)
data-processor
code-analyzer
report-generator

Technology Preferences

Stated preferences (you can choose differently):

• Node.js v24+ with ESM imports
• CLI-first (gh, aws, npm, jq over SDKs)
• Intention-revealing file names

Self-Referential Teaching

The skill-builder skill itself demonstrates best practices:

• Multi-file organization (SKILL.md, reference.md, examples.md)
• Progressive disclosure (core < 5K tokens)
• Clear type distinctions (skill, agent, command, scenario)
• Comprehensive validation
• Philosophy alignment

---

Reference Implementations

Official Anthropic Skills

Source: https://github.com/anthropics/skills

Document Skills (source-available):

• xlsx: Excel workbooks with formulas, charts
• pptx: PowerPoint presentations
• docx: Word documents
• pdf: PDF extraction and form filling

Creative Skills:

• algorithmic-art: Generative art using p5.js
• canvas-design: Visual output
• slack-gif-creator: Optimized GIFs

Development Skills:

• artifacts-builder: React/Tailwind HTML
• mcp-builder: MCP server guide
• webapp-testing: Playwright UI testing

Meta Skills:

• skill-creator: Framework for developing skills
• template-skill: Starter template

Community Skills

obra/superpowers (20+ skills):

• TDD workflow automation
• Debug session capture
• Collaborative problem-solving

Patterns Worth Adopting:

• Clear activation triggers
• Step-by-step workflows
• Error handling patterns
• Testing integration

---

Progressive Maturity Example

Showing how a skill evolves:

Stage 1: Experimental Skill

---
name: experimental-parser
description: Parses log files (experimental)
maturity: experimental
---

# Log Parser (Experimental)

## Purpose

Basic log file parsing and analysis.

[Minimal implementation...]

Stage 2: Beta Skill

---
name: log-parser
description: Parses system logs (Apache, nginx, syslog) and extracts error patterns
maturity: beta
---

# Log Parser

## Purpose

Production-ready log parsing with error pattern detection.

[Enhanced implementation with validation...]

Stage 3: Production Skill

---
name: log-analyzer
description: Comprehensive log analysis for Apache, nginx, syslog formats with error detection, pattern recognition, and anomaly identification
maturity: stable
version: 2.0.0
---

# Log Analyzer

## Purpose

Enterprise-grade log analysis with ML-powered anomaly detection.

[Complete implementation + reference.md + examples.md + scripts/...]

---

Updating Documentation

When to Update This File

Triggers for Updates:

1. Official Anthropic documentation changes 2. New skill patterns emerge in community 3. Breaking changes to skill format 4. New best practices identified 5. Quarterly review cycle

Update Process

1. Check Sources:

   # Visit each documentation source
   # Note changes since last update
   # Download updated examples

2. Update Relevant Sections:

   # Edit reference.md
   # Add version history entry
   # Update examples if needed

3. Test Updated Skill:

   # Create test skill with new patterns
   # Verify works correctly
   # Update examples.md with new patterns

4. Commit Changes:

   git add .claude/skills/skill-builder/
   git commit -m "docs: Update skill-builder reference documentation"

Sync Mechanism (Manual for Now)

Current Approach:

• Manual quarterly reviews
• Check official docs for changes
• Update reference.md and examples.md
• Version history tracking

Future Enhancement:

• Automated doc scraping
• Change detection
• PR generation for updates
• CI-driven validation

---

Maintainer: amplihack framework Last Review: 2025-11-15 Next Review Due: 2026-02-15 (Quarterly) Sources: 10 official and community documentation links

Skill Builder Reference Documentation

This file contains documentation about Claude Code skills, built from official sources. For the latest versions, see the URLs in SKILL.md.

---

Progressive Disclosure

Skills 3. YAML Frontmatter Specification 4. Progressive Disclosure Pattern 5. File Structure & Organization 6. Best Practices 7. Validation Guidelines 8. Common Patterns 9. Agent SDK Integration 10. Documentation Sources

---

How Claude Code Skills Work

Source: https://code.claude.com/docs/en/skills, https://docs.claude.com/en/docs/agent-sdk/skills

Core Concept

Skills are prompt-based conversation and execution context modifiers that inject specialized instructions and dynamically adjust tool permissions within scoped execution contexts.

Unlike traditional tools or function calling, skills:

• Modify Claude's behavior through instruction injection
• Load progressively (metadata → instructions → resources)
• Activate autonomously via description matching
• Scope permissions to specific tool subsets

Three-Tier Progressive Disclosure

Tier 1: Metadata (~100 tokens)

• YAML frontmatter with name and description
• Pre-loaded at startup for all available skills
• Enables discovery without loading full content
• Embedded in <available_skills> section

Tier 2: Core Instructions (<5,000 tokens)

• Full SKILL.md content loaded when skill deemed relevant
• All .md files in root directory load together
• Provides complete instructions and workflows
• Token budget critical for efficiency

Tier 3: Modular Resources (unbounded)

• Supporting files: scripts/, templates/, data/
• Loaded on-demand during execution
• Can include any file type
• Accessed via filesystem when needed

Autonomous Invocation

No Algorithmic Routing - Pure LLM reasoning for selection:

1. All skill descriptions formatted into natural language 2. Embedded in Skill tool's prompt (~15K character budget) 3. Claude's transformer decides relevance 4. No regex, keyword matching, or ML classification

What This Means:

• Description quality is CRITICAL for discovery
• Must include trigger keywords users naturally say
• Provide contextual usage scenarios
• Test with real user prompts

Execution Context Modification

Skills yield a contextModifier callback that:

• Dynamically adjusts tool permissions during execution
• Creates scoped privilege elevation pattern
• Pre-approves tools to bypass permission prompts
• Persists only during skill execution

Example:

---
name: read-only-analyzer
description: Analyzes code patterns without modifications
allowed-tools: Read, Grep, Glob # Restricts to read-only operations
---

During execution:

• Only Read, Grep, Glob available
• Write, Bash blocked
• Permissions revert after skill completes

---

Skill Architecture

Source: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

Design Philosophy

Progressive Disclosure: Reveal information only as needed

• Optimizes token usage
• Scales to many skills without context bloat
• Flexible through filesystem access

Autonomous Discovery: Let LLM decide relevance

• No external systems required
• Natural language interface
• Adaptable to new use cases

Modular Composition: Combine multiple skills

• Each skill focused on single responsibility
• Skills work together for complex tasks
• Easier maintenance and testing

Key Innovations

Dual-Message Communication:

• Visible metadata: User-facing status in conversation
• Hidden prompt (isMeta: true): API-sent instructions not rendered in UI
• Solves transparency-vs-clarity tension

Token-Efficient Discovery:

• ~15K character budget for all skill descriptions
• Forces concise, meaningful descriptions
• Strategic prioritization required

Scoped Permissions:

• Skills restrict tool access for safety
• Read-only workflows prevent accidents
• Reduces risk surface area

---

YAML Frontmatter Specification

Source: https://code.claude.com/docs/en/skills

Required Fields

---
name: skill-identifier # Required
description: Brief capability summary # Required
---

name:

• Lowercase alphanumeric with hyphens only
• Max 64 characters
• Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
• Example: analyzing-financial-data, pdf-form-filler

description:

• Max 1,024 characters (recommend 50-200)
• Most critical field for discovery
• Must combine: capabilities + triggers + context
• Good: "Calculate financial ratios (ROE, P/E, debt-to-equity) and interpret against industry benchmarks. Use for income statements or balance sheets."
• Bad: "Helps with data" (too vague)

Optional Fields

---
name: skill-name
description: Capability description
allowed-tools: Read, Write, Grep # Optional: Restrict available tools
disableModelInvocation: false # Optional: Opt-out of auto-activation
when_to_use: Alternative trigger # Optional: Additional trigger text
---

allowed-tools:

• Comma-separated list of tool names
• Security-critical for restricted workflows
• Example: Read, Grep, Glob for read-only skills

disableModelInvocation:

• Set to true to prevent automatic activation
• Skill must be explicitly requested
• Useful for experimental or dangerous skills

when_to_use:

• Alternative to description for activation
• Can be more verbose than description
• Provides additional context clues

Validation Rules

From https://github.com/anthropics/claude-cookbooks/tree/main/skills:

1. YAML Syntax: Must parse correctly with yaml.safe_load() 2. Required Fields: Both name and description must be present 3. Name Format: Lowercase letters, numbers, hyphens only 4. Description Length: Between 10 and 1,024 characters 5. No Duplicates: Name must be unique across all skills

---

Progressive Disclosure Pattern

Source: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

Why Progressive Disclosure

Problem: Skills compete for limited context window Solution: Load information incrementally as needed

Benefits:

• Token efficiency (skills don't compete)
• Scalable (can have many skills)
• Flexible (unbounded resources via filesystem)
• Better user experience (quick start vs deep dive)

Implementation Strategy

SKILL.md (Core - 1,000-2,000 tokens TARGET):

• YAML frontmatter with source_urls
• Overview and purpose (2-3 sentences)
• Quick start examples
• Core concepts reference (NOT exhaustive details)
• Common patterns (3-5 most frequent use cases)
• MANDATORY: Navigation guide ("When to Read Supporting Files")
• High-level workflow instructions

Split based on CONTENT, not just token count:

• SKILL.md = Beginner-friendly, covers 80% of use cases
• Supporting files = Expert deep-dives, edge cases, internals

reference.md (Deep Technical Details):

• Complete API reference with all methods and parameters
• Detailed configuration options and environment setup
• Architecture and internals documentation
• Comprehensive tool/schema specifications
• Advanced configuration patterns
• Security considerations

examples.md (Practical Implementation):

• Working code examples (copy-paste ready)
• Step-by-step implementation guides
• Common integration patterns
• Edge cases and error handling
• Real-world usage scenarios
• Advanced use case demonstrations

patterns.md (Production Expertise - Optional):

• Production-ready architectural patterns
• Performance optimization techniques
• Security best practices and anti-patterns
• Scaling strategies
• Common pitfalls and solutions
• Testing and debugging approaches

scripts/ (Executable Utilities):

• Deterministic operations
• Mathematical calculations
• Data parsing/validation
• API integrations
• Offload computation from LLM

Token Budget Guidelines

Recommended Sizes:

• SKILL.md: 1,000-2,000 tokens (strict target, not "up to 5,000")
• reference.md: 2,000-5,000 tokens (comprehensive but focused)
• examples.md: 1,500-3,000 tokens (practical, copy-paste ready)
• patterns.md: 1,500-3,000 tokens (production wisdom)

When to Split:

• Always split skills with supporting documentation (even if SKILL.md < 2,000 tokens)
• Progressive disclosure is about CONTENT organization, not just token count
• Better to have 1,500-token SKILL.md + reference.md than 4,000-token monolithic SKILL.md
• Reference example: agent-sdk (514-line SKILL.md with 4 supporting files)

Loading Behavior

All .md files in root load together when skill activates:

• SKILL.md (always)
• reference.md, examples.md, patterns.md (if present)
• Enables modular documentation
• Each file focused on specific aspect

Supporting files load on-demand:

• Scripts execute when referenced
• Templates read when needed
• Resources accessed during processing

Navigation Guide Requirements

MANDATORY for multi-file skills:

Every skill with supporting documents MUST include a "Navigation Guide" section in SKILL.md that explicitly tells Claude when to read each file.

Template:

## Navigation Guide

### When to Read Supporting Files

**reference.md** - Read when you need:

- [Specific use cases requiring this file]
- [Technical details not in SKILL.md]
- [Complete API or configuration reference]

**examples.md** - Read when you need:

- [Working code for specific patterns]
- [Step-by-step implementation guides]
- [Integration examples]

**patterns.md** - Read when you need:

- [Production best practices]
- [Performance optimization]
- [Security patterns]

Good Example: ~/.amplihack/.claude/skills/claude-agent-sdk/SKILL.md lines 376-408

• Lists each supporting file
• Clearly states WHEN to read it
• Specific enough to guide Claude's decision
• Prevents unnecessary file reads

Bad Example: Omitting navigation guide entirely

• Claude doesn't know when to load supporting files
• May load everything (token waste) or nothing (missing details)
• User experience degrades

---

File Structure & Organization

Source: https://github.com/anthropics/skills (official examples)

Standard Skill Directory

skill-name/
├── SKILL.md          # REQUIRED: Primary instructions with YAML frontmatter
├── reference.md      # Optional: Detailed documentation
├── examples.md       # Optional: Usage examples and sample outputs
├── scripts/          # Optional: Executable utilities
│   ├── process.py
│   ├── validate.js
│   └── helpers.sh
├── templates/        # Optional: Reusable templates
│   ├── report.md
│   └── config.json
└── resources/        # Optional: Data files and assets
    ├── benchmarks.csv
    └── schemas.json

Storage Locations

Personal Skills (~/.claude/skills/):

• Available across all projects
• User-specific workflows
• Experimental capabilities
• Installation: git clone <repo> ~/.claude/skills/skill-name

Project Skills (~/.amplihack/.claude/skills/):

• Shared with team via git
• Project-specific expertise
• Automatically available when team pulls updates
• Committed to version control

Plugin Skills:

• Bundled with Claude Code plugins
• Install automatically with parent plugin
• Managed by plugin system

Multi-File Organization

From https://github.com/anthropics/claude-cookbooks/tree/main/skills:

Why Split Across Files:

• Maintainability: Easier to update specific sections
• Token Efficiency: Load only what's needed
• Readability: Focused, scannable documentation
• Versioning: Track changes to specific aspects

When to Split:

• Target SKILL.md at 1,000-2,000 tokens (use supporting files for rest)
• Many examples → Separate examples.md
• Complex logic → Scripts in scripts/
• Reusable patterns → Templates in templates/
• Production patterns → patterns.md
• Complete API reference → reference.md

Source URL Requirements

When to Include source_urls in YAML frontmatter:

MANDATORY for skills based on external documentation:

• Official product documentation
• GitHub repositories
• Technical blog posts
• API references
• Tutorial series

Format:

---
name: skill-name
description: Brief description
source_urls:
  - https://primary-documentation-source.com
  - https://github.com/org/repo/docs
  - https://blog.example.com/technical-guide
---

Benefits:

• Attribution: Gives credit to original sources
• Drift Detection: Enables automated checks for documentation updates
• User Reference: Users can consult authoritative sources directly
• Maintenance: Maintainers know where to check for updates

Good Examples:

• agent-sdk skill: Lists 4 official Anthropic documentation URLs
• Skills derived from open-source projects: Include GitHub repo URL
• Skills based on API docs: Include API documentation URL

Bad Examples:

• Omitting source_urls when skill is clearly based on external docs
• Generic URLs (e.g., just "https://github.com") instead of specific documentation links
• Broken or outdated URLs

Reference Document Structure

reference.md should follow this template:

# [Skill Name] - Complete API Reference

## Architecture

[Deep dive into how the system works internally]

### Component 1

[Detailed explanation]

### Component 2

[Detailed explanation]

## Setup & Configuration

[Complete configuration options]

### Environment Setup

[Detailed steps]

### Advanced Configuration

[Expert-level options]

## API Reference

[Complete method/function/tool reference]

### Method/Tool 1

**Description:** [What it does]
**Parameters:** [Complete parameter list with types]
**Returns:** [Return values]
**Examples:** [Code examples]
**Errors:** [Error conditions]

### Method/Tool 2

[Same structure]

## Advanced Topics

[Expert-level concepts]

## Troubleshooting

[Common issues and solutions]

Key Principles:

• Comprehensive but organized
• Every parameter documented
• Code examples for complex features
• Cross-references to examples.md for working code
• Table of contents for navigation

examples.md should follow this template:

````markdown

[Skill Name] - Working Examples

Basic Examples

Example 1: [Simple Use Case]

[Description of what this demonstrates]

```[language] [Complete, copy-paste ready code]

Expected Output:

[What user should see]

Explanation: [Key points about the example]

Example 2: [Another Common Use Case]

[Same structure]

Intermediate Examples

Example 3: [More Complex Scenario]

[Complete working code with explanation]

Advanced Examples

Example 4: [Production Pattern]

[Real-world implementation]

Integration Examples

Example 5: [Integrating with System X]

[How to use with other tools/systems]

````

Key Principles:

• Every example is complete and runnable
• Clear expected outputs
• Explains WHY, not just HOW
• Progresses from simple to complex
• Covers common integration scenarios

patterns.md should follow this template:

# [Skill Name] - Production Patterns

## Architectural Patterns

### Pattern 1: [Pattern Name]
**Use Case:** [When to use this]
**Implementation:** [How to implement]
**Benefits:** [Why this works]
**Tradeoffs:** [What you give up]

### Pattern 2: [Another Pattern]
[Same structure]

## Performance Optimization

### Optimization 1: [Technique]
[Details and examples]

## Security Best Practices

### Practice 1: [Security Pattern]
**Risk:** [What this protects against]
**Implementation:** [How to do it]

## Anti-Patterns

### Anti-Pattern 1: [What NOT to do]
**Problem:** [Why this is bad]
**Better Approach:** [What to do instead]

## Common Pitfalls

### Pitfall 1: [Common Mistake]
**Symptom:** [How it manifests]
**Cause:** [Why it happens]
**Solution:** [How to fix]

Key Principles:

• Focus on production lessons learned
• Include anti-patterns (what NOT to do)
• Explain tradeoffs honestly
• Real-world war stories
• Performance and security emphasis

---

Best Practices

Source: https://docs.claude.com/en/docs/agent-sdk/skills (Best Practices section)

Description Quality (MOST CRITICAL)

Effective descriptions combine specificity + triggers + context:

✅ Good: "Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with .xlsx files or data analysis requests."

✅ Good: "Calculate financial ratios (ROE, P/E, current ratio, debt-to-equity) and interpret against industry benchmarks. Use for income statements, balance sheets, or financial analysis."

❌ Bad: "Helps with data" (too vague) ❌ Bad: "Document processor" (no trigger keywords) ❌ Bad: "Analysis tool" (lacks context)

Description Checklist:

• [ ] Specific capabilities listed (verbs: analyze, generate, calculate)
• [ ] Trigger keywords users naturally say
• [ ] File extensions or formats mentioned (.xlsx, .pdf, JSON)
• [ ] Use case context provided
• [ ] Under 1,024 characters (ideally 50-200)

Single Responsibility Principle

Focus on ONE expertise area:

✅ Good: Separate skills for different domains

• analyzing-financial-statements (financial ratios only)
• filling-pdf-forms (PDF form processing only)
• analyzing-excel-data (Excel analysis only)

❌ Bad: Monolithic skill

• document-processing (tries to handle all document types)

Benefits:

• Better discovery (precise descriptions)
• Easier maintenance
• Composable (combine multiple skills)
• Clearer token budget

Token Budget Management

Recommended limits (from Anthropic engineering):

• Frontmatter description: <500 chars (ideal), 1,024 max
• SKILL.md total: <5,000 tokens
• Supporting .md files: <3,000 tokens each
• Total skill context: <15,000 tokens

Optimization strategies:

1. Move detailed documentation to reference.md 2. Extract code to scripts/ directory 3. Use examples.md for sample outputs 4. Reference external resources by URL 5. Progressive disclosure through multiple files

Security Safeguards

Critical security practices:

• ⚠️ Never hardcode API keys, credentials, or secrets
• ⚠️ Exclude sensitive data from skill documentation
• ⚠️ Sanitize all inputs in scripts
• ⚠️ Use allowed-tools to restrict capabilities
• ⚠️ Maintain audit trails for compliance
• ⚠️ Only install skills from trusted sources

Example: Read-only skill

---
name: analyzing-code
description: Analyze code patterns and architecture
allowed-tools: Read, Grep, Glob # Cannot modify files
---

---

Validation Guidelines

Pre-Creation Validation

Name Validation:

import re

def validate_skill_name(name):
    """Validate skill name follows conventions"""
    pattern = r'^[a-z0-9]+(-[a-z0-9]+)*$'
    if not re.match(pattern, name):
        return False, "Name must be kebab-case"
    if len(name) < 3:
        return False, "Name too short (minimum 3 characters)"
    if len(name) > 64:
        return False, "Name too long (maximum 64 characters)"
    return True, "Name is valid"

YAML Validation:

import yaml

def validate_yaml_frontmatter(content):
    """Validate YAML frontmatter in skill content"""
    try:
        parts = content.split('---', 2)
        if len(parts) < 3:
            return False, "Missing YAML frontmatter delimiters"

        frontmatter = yaml.safe_load(parts[1])

        # Check required fields
        required = ['name', 'description']
        missing = [f for f in required if f not in frontmatter]
        if missing:
            return False, f"Missing required fields: {', '.join(missing)}"

        # Validate description length
        desc_len = len(frontmatter['description'])
        if desc_len < 10:
            return False, f"Description too short ({desc_len} chars, min 10)"
        if desc_len > 1024:
            return False, f"Description too long ({desc_len} chars, max 1024)"

        return True, "YAML frontmatter is valid"

    except yaml.YAMLError as e:
        return False, f"YAML syntax error: {e}"

Token Budget Validation

import tiktoken

def validate_token_budget(skill_path):
    """Validate skill stays within token budget"""
    encoding = tiktoken.encoding_for_model("claude-sonnet-4-5")

    skill_md = (skill_path / "SKILL.md").read_text()
    tokens = len(encoding.encode(skill_md))

    if tokens > 20000:
        return False, f"Exceeds absolute maximum ({tokens} tokens > 20,000)"
    if tokens > 5000:
        return True, f"Warning: Very high token count ({tokens} tokens > 5,000). Consider splitting."
    if tokens > 2000:
        return True, f"Warning: Above target ({tokens} tokens > 2,000). Should use supporting files."
    if tokens < 500:
        return True, f"Notice: Very small skill ({tokens} tokens). Consider if this is too minimal."
    return True, f"Token budget optimal ({tokens} tokens, target: 1,000-2,000)"

Token Budget Philosophy:

• Target: 1,000-2,000 tokens for SKILL.md
• Warning at 2,000+: Should move content to supporting files
• Error at 20,000+: Absolute maximum, must split
• Progressive disclosure is about content organization, not just staying under 5,000 tokens

Structure Validation

File Checklist:

• [ ] SKILL.md exists with valid YAML frontmatter
• [ ] All required sections present (Purpose, Usage, Instructions)
• [ ] No broken links or missing references
• [ ] Scripts (if any) are executable
• [ ] Examples are clear and working
• [ ] No TODO/FIXME markers (zero-BS principle)

---

Common Patterns

Source: https://github.com/anthropics/claude-cookbooks/blob/main/skills/notebooks/03_skills_custom_development.ipynb

Pattern 1: Read-Process-Write

Use Case: File transformations, data processing

Tools: Read, Write, code_execution

Template:

---
name: processing-csv-reports
description: Transform CSV data into formatted reports with calculations
allowed-tools: Read, Write, code_execution
---

# CSV Report Processor

## Purpose
Transforms raw CSV data into formatted analytical reports.

## Instructions
1. Read CSV file using Read tool
2. Parse and validate data structure
3. Execute calculations via code_execution
4. Generate formatted report
5. Write output using Write tool

Pattern 2: Search-Analyze-Report

Use Case: Codebase introspection, pattern detection

Tools: Grep, Glob, Read

Template:

---
name: analyzing-dependencies
description: Analyze project dependencies and identify version conflicts
allowed-tools: Grep, Glob, Read
---

# Dependency Analyzer

## Purpose
Identifies and analyzes project dependencies, detecting conflicts.

## Instructions
1. Use Glob to find dependency files (package.json, requirements.txt)
2. Use Grep to extract version information
3. Use Read for detailed dependency inspection
4. Analyze conflicts and compatibility
5. Generate report with recommendations

Pattern 3: Wizard-Style Multi-Step

Use Case: Interactive processes requiring user confirmation

Tools: AskUserQuestion, Read, Write

Template:

---
name: configuring-systems
description: Interactive system configuration with validation checkpoints
allowed-tools: AskUserQuestion, Read, Write
---

# System Configurator

## Purpose
Guides users through system configuration with validation.

## Instructions
1. Use AskUserQuestion for preferences
2. Read existing configuration
3. Validate choices against constraints
4. Ask for confirmation
5. Write updated configuration

---

Agent SDK Integration

Source: https://docs.claude.com/en/docs/agent-sdk/skills

Configuration Requirements

To use skills with the SDK, you MUST configure filesystem loading:

Python:

from anthropic import Anthropic

options = ClaudeAgentOptions(
    cwd="/path/to/project",
    setting_sources=["user", "project"],  # CRITICAL: Enables skill loading
    allowed_tools=["Skill", "Read", "Write", "Bash"]  # Must include "Skill"
)

async for message in query(prompt="Help process this PDF", options=options):
    print(message)

TypeScript:

const options = {
  cwd: "/path/to/project",
  settingSources: ["user", "project"], // CRITICAL
  allowedTools: ["Skill", "Read", "Write", "Bash"],
};

Common Pitfall

Most common SDK issue: Not configuring setting_sources/settingSources

Without this, the SDK doesn't load any filesystem settings including skills.

Tool Restrictions

Claude Code vs SDK:

• In Claude Code CLI: allowed-tools in YAML frontmatter restricts tools
• In SDK: Tool access controlled by allowedTools option only
• YAML allowed-tools has no effect in SDK applications

---

Documentation Sources

Official Anthropic Documentation

1. Claude Code Skills: https://code.claude.com/docs/en/skills

• Primary reference for CLI skills
• File structure and organization
• Discovery and invocation

2. Agent SDK Skills: https://docs.claude.com/en/docs/agent-sdk/skills

• SDK-specific configuration
• setting_sources requirement
• TypeScript/Python integration

3. Agent Skills Engineering Blog: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

• Architecture and design philosophy
• Progressive disclosure pattern
• Autonomous invocation model
• Execution context modification

4. Claude Cookbooks: https://github.com/anthropics/claude-cookbooks/tree/main/skills

• Three progressive Jupyter notebooks
• Financial analysis examples
• Custom skill development tutorial
• Sample data and templates

5. Anthropic Skills Repository: https://github.com/anthropics/skills

• 14 official skill examples
• Source-available document skills
• Meta skills (skill-creator, template-skill)
• Best practice implementations

Community Resources

6. metaskills/skill-builder: https://github.com/metaskills/skill-builder

• Meta-skill for creating skills
• Opinionated guidance (gerund naming, Node.js, CLI-first)
• Self-referential teaching approach
• Excellent progressive scaffolding

7. obra/superpowers: https://github.com/obra/superpowers

• 20+ battle-tested skills
• TDD, debugging, collaboration patterns
• Production-proven implementations

8. Awesome Claude Skills Collections:

• travisvn/awesome-claude-skills
• ComposioHQ/awesome-claude-skills
• BehiSecc/awesome-claude-skills

Deep Dives

9. First Principles Analysis: https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/

• Architectural decisions explained
• Progressive disclosure pattern deep-dive
• Dual-message communication model
• Execution context modification

10. Simon Willison Blog: https://simonwillison.net/2025/Oct/16/claude-skills/

• "Skills are maybe a bigger deal than MCP"
• Comparison with other systems
• Practical implications

---

Skill Builder Meta-Documentation

How to Keep This Updated

Manual Sync Process:

1. Check official docs quarterly: https://code.claude.com/docs/en/skills 2. Review Agent SDK changes: https://docs.claude.com/en/docs/agent-sdk/skills 3. Monitor Anthropic engineering blog for updates 4. Track community skill examples for new patterns 5. Update this file when changes detected

Automated Sync (Future Enhancement):

• Could use web scraping to detect doc changes
• Compare current content vs source
• Flag outdated sections
• Generate update PRs

Version History

v1.0.0 (2025-11-15):

• Initial comprehensive research compilation
• 10 primary documentation sources
• All core patterns documented
• Agent SDK integration included
• Best practices from official guides

Update Protocol: When official documentation changes:

1. Note change in version history 2. Update relevant section 3. Increment version number 4. Add changelog entry

---

Token Budget Optimization Tips

From Anthropic Engineering:

1. Defer to Scripts: Offload deterministic operations

• Sorting algorithms → Python/JS scripts
• Mathematical calculations → code_execution
• Data parsing → dedicated parsers
• API calls → script wrappers

2. Use External References: Link instead of embedding

• Industry benchmarks → URL references
• Long examples → examples.md
• API docs → external links
• Detailed specs → reference.md

3. Semantic Compression: Say more with less

• Use bullet points over paragraphs
• Prefer concise examples
• Remove redundant explanations
• Consolidate similar sections

4. Progressive Disclosure: Structure strategically

• SKILL.md: Core workflow only
• reference.md: Deep details
• examples.md: Usage patterns
• Scripts: Implementation logic

---

Last Updated: 2025-11-15 Maintainer: amplihack framework Sources: 10 official and community references