Example Skill

Architecture Overview

Core Components

• SKILL.md - Core skill definition with routing logic (you're reading it now!)
• workflows/ - Specific task workflows for discrete operations
• assets/ - Templates, references, and helper files

Progressive Disclosure

1. Metadata (always loaded) - Name, description, triggers
2. Instructions (loaded when triggered) - This SKILL.md content
3. Resources (loaded as needed) - Individual workflow and asset files

Included Workflows

1. simple-task.md

2. complex-task.md

3. parallel-task.md

Routing Logic

User Intent → Skill Activation → Workflow Selection → Execution

Example Flow:
"Show me a simple example"
    ↓ (matches trigger)
example-skill loads
    ↓ (analyzes intent: "simple")
simple-task.md selected
    ↓
Workflow executes

Assets

assets/

• template.md

  - Example template file

• reference.md

  - Example reference material

Usage Examples

Basic Usage

User: "Show me a simple example"
→ Loads example-skill
→ Executes simple-task.md workflow
→ Returns basic workflow demonstration

Complex Usage

User: "I need a complex multi-step example"
→ Loads example-skill
→ Executes complex-task.md workflow
→ Returns structured multi-step demonstration

Parallel Usage

User: "How do I parallelize work?"
→ Loads example-skill
→ Executes parallel-task.md workflow
→ Returns agent orchestration demonstration

Creating Your Own Skill

1. Copy the structure:
   bash

   cp -r ~/.claude/skills/example-skill ~/.claude/skills/your-skill-name

2. Update SKILL.md:
   • Change name and description in frontmatter
   • Update trigger phrases
   • Replace example content with your skill's purpose
3. Create workflows:
   • Add workflow files in workflows/ directory
   • Each workflow = one specific task
   • Name workflows descriptively
4. Add assets (optional):
   • Templates, references, helper scripts
   • Keep organized in assets/ directory
5. Test activation:
   • Test trigger phrases
   • Verify workflow routing
   • Ensure natural language works

Best Practices

Skill Organization

• ✅ One skill per domain/topic area
• ✅ Multiple workflows within a skill
• ✅ Clear trigger phrases
• ❌ Don't create skills for one-off tasks
• ❌ Don't duplicate knowledge across skills

Workflow Design

• ✅ Self-contained with clear steps
• ✅ Focused on ONE specific task
• ✅ Include trigger phrases
• ❌ Don't make workflows too granular
• ❌ Don't duplicate skill context

Natural Language Routing

• ✅ Use descriptive trigger phrases
• ✅ Test with variations
• ✅ Think like a user
• ❌ Don't require exact phrase matching
• ❌ Don't make users memorize commands

Technical Details

File Structure

example-skill/
├── SKILL.md              # This file (core definition)
├── workflows/            # Specific task workflows
│   ├── simple-task.md
│   ├── complex-task.md
│   └── parallel-task.md
├── assets/               # Supporting resources
│   ├── template.md
│   └── reference.md
└── README.md             # Overview documentation

Loading Behavior

1. Skill metadata always loaded (YAML frontmatter)
2. SKILL.md body loaded when skill activates
3. Individual workflows loaded when selected
4. Assets loaded when referenced

Integration Points

• Natural Language: Trigger phrases activate skill
• Other Skills: Can reference this skill's workflows
• Agents: Can invoke specific workflows
• Commands: Can route to this skill's workflows

Documentation

• Architecture: See

  ~/Projects/PAI/docs/ARCHITECTURE.md

• Migration Guide: See

  ~/Projects/PAI/docs/MIGRATION.md

• Skill Development: See

  ~/.claude/skills/create-skill/

References

• Anthropic Skills: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview
• PAI Repository: https://github.com/danielmiessler/Personal_AI_Infrastructure
• v1.2.0 Changes: Skills-as-Containers migration completed 2025-10-31