Skill Factory

Role: Claude Code Skill Architect Purpose: Create properly structured skills following official conventions

When to Activate

• Creating new Claude Code skills
• Refactoring existing skills
• Designing skill architectures
• Setting up skill file structures

Skill Creation Process

Step 1: Requirements Gathering

Ask the user:

1. What capability? - What should this skill do?
2. When trigger? - What words/phrases should activate it?
3. What domain? - What expertise area does it cover?
4. Tool restrictions? - Should tools be limited (read-only, etc.)?
5. Supporting files? - Need workflows, templates, references?

Step 2: Create Directory Structure

~/.claude/skills/[skill-name]/
├── SKILL.md              # Required - main skill file
├── workflows/            # Optional - step-by-step task guides
│   └── [workflow].md
├── templates/            # Optional - reusable templates
│   └── [template].md
├── references/           # Optional - reference documentation
│   └── [reference].md
└── examples/             # Optional - concrete examples
    └── [example].md

Step 3: Write SKILL.md

Use the template at templates/skill-template.md

Frontmatter Specification

---
name: skill-name              # Required: lowercase, hyphens only, max 64 chars
description: |                # Required: max 1024 chars, CRITICAL for discovery
  Brief description of what this skill does.

  Triggers: keyword1, keyword2, phrase1

  Expertise: area1, area2, area3

# Optional fields:
triggers:                     # List of trigger terms (for documentation)
  - keyword1
  - keyword2
domains:                      # Expertise domains
  - domain1
  - domain2
allowed-tools: Read, Grep     # Restrict available tools (optional)
tier: 1                       # Skill tier (1-5, optional)
voice_id: <id>                # ElevenLabs voice ID (optional)
---

Description Best Practices

The description is CRITICAL - it determines when Claude activates the skill.

Bad:

description: Helps with documents

Good:

description: |
  Extract text and tables from PDF files, fill forms, merge documents.
  Use when working with PDF files or when user mentions PDFs, forms,
  or document extraction.

  Triggers: PDF, extract text, fill form, merge PDF, document extraction

  Expertise: pypdf, pdfplumber, form filling, text extraction

Body Structure Template

# Skill Name

**Role:** [Specialist type]
**Tone:** [Communication style]
**Purpose:** [What it accomplishes]

## When to Activate

- Trigger condition 1
- Trigger condition 2

## Core Expertise

- Expertise area 1
- Expertise area 2

## Workflow

[For complex skills, link to workflows/]

## Response Format

[Expected output structure]

🎯 COMPLETED: [SKILL:skill-name] [task description]
🗣️ CUSTOM COMPLETED: [voice-optimized message]

Dynamic Context Injection

Use !command`` syntax to inject live data when a skill loads. The command runs locally before Claude sees the content, and the output replaces the placeholder.

Example:

## Current State
Recent files: !`ls -t ~/Obsidian/<YOUR_VAULT>/Unsorted/ 2>/dev/null | head -10`
Today: !`date +%Y-%m-%d`

Best practices:

• Always add 2>/dev/null to prevent error output in skill context
• Use | head -N to limit output size
• Keep injections minimal — they run on every skill load
• Useful for: dates, file listings, git status, system state

Tier System

Tier	Category	Auto-activate	Examples
1	Core Specialists	Yes	engineering, architecture, security
2	Research & Analysis	Yes	research, data-analysis
3	Writing	Yes	technical-writing, swedish-academic
4	Intelligence	On match	ekonomisk-osint, geolocation
5	Domain Systems	On match	omvarld-* system

File Organization Patterns

Simple Skill (single file)

skill-name/
└── SKILL.md

Standard Skill

skill-name/
├── SKILL.md
├── workflows/
│   └── main-workflow.md
└── references/
    └── key-reference.md

Complex Skill

skill-name/
├── SKILL.md
├── workflows/
│   ├── workflow-1.md
│   └── workflow-2.md
├── templates/
│   └── output-template.md
├── references/
│   ├── reference-1.md
│   └── reference-2.md
└── examples/
    └── example-usage.md

Quality Checklist

• Name: lowercase, hyphens, max 64 chars
• Description: under 1024 chars, includes triggers
• Triggers: specific, user-centric language
• Body: clear structure, actionable guidance
• Response format: includes completion markers
• Files: progressive disclosure, <500 lines main file

After Creation

1. Add to SKILLS-INDEX.md
2. Test activation with natural prompts
3. Validate YAML syntax
4. Document in learnings if relevant

Templates

See templates/skill-template.md for the complete starter template.

Response Format

🎯 COMPLETED: [SKILL:skill-factory] [Created X skill with Y structure]
🗣️ CUSTOM COMPLETED: [SKILL:skill-factory] [Skill architected]