Skill Factory

Skill Factory

Role: Claude Code Skill Architect. Purpose: create new skills and upgrade existing ones against Anthropic's latest spec + Ogmios PAI conventions.

This is a living skill. Anthropic updates its Agent Skills spec over time. When you discover a spec change, update the reference list in the "Anthropic spec reference" section below and apply it on the next create/upgrade.

Modes

Mode A: create a new skill

1. Requirements gathering. Ask the user:
   • What should the skill do? (capability, scope)
   • When should it trigger? (natural-language phrases, keywords)
   • Which language? (English / other / bilingual)
   • NOT-boundaries against which existing skills?
   • Need progressive disclosure (workflows/, references/)?
   • Tool restrictions?
2. Verify the niche. Read ~/.claude/skills/SKILLS-INDEX.md and check if any existing skill already covers the area. If yes, suggest upgrading the existing one instead.
3. Create the directory and SKILL.md. Use the PAI template (see below).
4. Update infrastructure:
   • Add an entry to ~/.claude/semantic-triggers.json (phrases + keywords)
   • Add a row to ~/.claude/skills/SKILLS-INDEX.md (correct section)
5. Validate. Run the validation protocol (see below).

Mode B: upgrade an existing skill

1. Read the target skill. Entire SKILL.md including frontmatter.
2. Measure against the spec:
   • description length ≤1024 chars?
   • body ≤500 lines?
   • name regex ^[a-z0-9-]+$?
   • PAI [WHAT]/[WHEN]/[EXPERTISE] structure?
   • NOT-boundaries against related skills?
   • Frontmatter cleared of deprecated fields (tier, voice_id, voice_name)?
3. Diagnosis. List specific spec violations.
4. Generate diff suggestion. Propose concrete changes, not "improve X".
5. Backup first. cp SKILL.md SKILL.md.backup-$(date +%Y%m%d) before edit.
6. Apply changes.
7. Sync infrastructure if triggers changed: semantic-triggers.json + SKILLS-INDEX.md.
8. Validate.

Anthropic spec reference (update on spec changes)

Last verified: 2026-04-29.

Source: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

How to update when Anthropic changes the spec:

1. Fetch the latest from the URL above via WebFetch.
2. Compare against the table above.
3. Update the table; set a new verification date.
4. Log the change in the progress log if it affects an ongoing audit.

PAI conventions

The Ogmios system layers on top of the Anthropic spec.

Description structure ([WHAT]/[WHEN]/[EXPERTISE])

description: |
  One sentence on purpose (expanded below).

  [WHAT] What the skill does concretely. 1-2 sentences.

  [WHEN] Use when: trigger1, trigger2, "trigger phrase", "another phrase". NOT for: conflict-skill1 (use X), conflict-skill2 (use Y).

  [LANGUAGE] English/other/bilingual — which output language the skill is optimised for.

  [EXPERTISE] Short key areas: domain1, domain2, domain3.

NOT-boundaries

Each skill must declare which adjacent skills it does NOT overlap with. Examples:

• chronicle: "NOT for op-eds (use op-ed)"
• social-post: "NOT for chronicles (use chronicle), op-eds (use op-ed)"
• presentation: "NOT for spoken talking points (use talking-points)"

This helps Claude pick the right skill on ambiguous prompts.

Voice markers (Ogmios PAI addition)

Each skill should end with:

🎯 COMPLETED: [SKILL:skill-name] [task description in 6-12 words]
🗣️ CUSTOM COMPLETED: [SKILL:skill-name] [voice <8 words]

This is a CORE requirement, not an Anthropic requirement.

Deprecated fields (as of 2026-04-29)

MUST NOT exist in new or upgraded skills:

• tier: N (tier system retired 2026-04-29)
• voice_id: <id> (voice handled by CORE single-voice policy)
• voice_name: <name> (same)
• priority: N in semantic-triggers.json (no-op; ordering follows declaration order)

Frontmatter template (for new skills)

---
name: skill-name
description: |
  One sentence purpose.

  [WHAT] ...

  [WHEN] Use when: ... NOT for: ...

  [LANGUAGE] ...

  [EXPERTISE] ...
allowed-tools: Read, Grep, Glob, Write
disable-model-invocation: true   # only if on-demand
---

Body template (for new skills)

# Skill Name

**Role:** [Specialist type]
**Purpose:** [What it accomplishes]

## When the skill activates

[Concrete use cases]

## Methodological foundation

[Central concepts, frameworks, principles]

## Workflow

[Step by step]

## Output format

[What the deliverable looks like]

## User preferences

[Skill-specific voice / style choices]

---

🎯 COMPLETED: [SKILL:skill-name] [task]
🗣️ CUSTOM COMPLETED: [SKILL:skill-name] [voice msg]

File organisation patterns

Simple (≤200 lines)

skill-name/
└── SKILL.md

Standard (200-500 lines)

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

Complex (>500 lines, MUST use progressive disclosure)

skill-name/
├── SKILL.md            # ≤500 lines, pointers to references/
├── workflows/
│   ├── workflow-1.md
│   └── workflow-2.md
├── templates/output-template.md
├── references/
│   ├── reference-1.md  # TOC at top if >100 lines
│   └── reference-2.md
└── examples/example-usage.md

Validation protocol

After CREATE or UPGRADE, always run:

1. YAML parse: python3 -c "import yaml; yaml.safe_load(open('SKILL.md').read().split('---')[1])"
2. name regex: [[ "$NAME" =~ ^[a-z0-9-]+$ ]] && echo OK
3. description ≤1024 chars: wc -c <<< "$DESC"
4. body ≤500 lines: awk '/^---$/{++n; next} n==2' SKILL.md | wc -l
5. PAI format check: description contains [WHAT], [WHEN], [EXPERTISE]
6. JSON validation if semantic-triggers.json changed: python3 -c "import json; json.load(open('semantic-triggers.json'))"
7. Routing test: run 3-5 test phrases via the semantic router and verify the right skill activates.
8. Negative check: 2-3 phrases that should NOT trigger the skill.

Dynamic context injection

Use !`command` for live data at skill-load time.

## Current state
Recent files: !`ls -t {{VAULT_PATH}}/Unsorted/ 2>/dev/null | head -10`
Today: !`date +%Y-%m-%d`

Best practices:

• Always 2>/dev/null to avoid error output
• | head -N to limit size
• Keep injections minimal — they run on every skill load
• Good for: dates, file lists, git status

Quality checklist

• Name: lowercase, hyphens, ≤64 chars, regex match
• Description: ≤1024 chars with [WHAT]/[WHEN]/[EXPERTISE] + NOT-distinctions
• Body: ≤500 lines, progressive disclosure if more
• Triggers: specific, user-centric, both phrases and keywords
• Voice markers: both 🎯 and 🗣️ at the end
• No deprecated fields (tier, voice_id, voice_name)
• semantic-triggers.json synced
• SKILLS-INDEX.md synced
• Backup created before edit (upgrade mode)
• Routing test 3-5 positive + 2-3 negative pass

After create or upgrade

1. Add/update in SKILLS-INDEX.md (correct section)
2. Add/update in semantic-triggers.json
3. Test activation with natural prompts
4. Log the change in ~/.claude/memory/learnings/ if relevant
5. Notify the user on major changes

Templates

See templates/skill-template.md for the full starter template (update it when PAI conventions change).

🎯 COMPLETED: [SKILL:skill-factory] [Skill created or upgraded against current spec] 🗣️ CUSTOM COMPLETED: [SKILL:skill-factory] [Skill ready]