# Skill Factory

> Create or upgrade Claude Code skills per Anthropic's latest spec and Ogmios PAI conventions. A living tool that tracks the Anthropic pattern's evolution. [WHAT] Two modes: (1) CREATE a new skill with SKILL.md, frontmatter, [WHAT]/[WHEN]/[EXPERTISE] format, NOT-distinctions, progressive disclosure. (2) UPGRADE an existing skill — diagnose against the spec, generate a diff, apply. [WHEN] Use when: create skill, new skill, upgrade skill, refactor skill, anthropic update, skill audit. NOT for: social posts (use social-post), documents (use document-factory). [LANGUAGE] English for meta-language. [EXPERTISE] Anthropic Agent Skills spec, Ogmios PAI conventions, YAML frontmatter, progressive disclosure, semantic-triggers/SKILLS-INDEX sync, validation.

- Skill: `carlheath/skill-factory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add carlheath/skill-factory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/carlheath/skill-factory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: carlheath (https://skillmd.com/u/carlheath)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/carlheath/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`

| Requirement | Value | Measurement |
|---|---|---|
| name | regex `^[a-z0-9-]+$`, ≤64 chars | Lowercase, hyphens, no underscore/space/uppercase |
| description | ≤1024 chars | Determines Claude's auto-discovery |
| body | ≤500 lines (recommendation) | Beyond: use progressive disclosure |
| disable-model-invocation | optional `true` | Skill becomes on-demand only, no auto-discovery |
| allowed-tools | optional comma-separated string | Restrict the skill's tool access |
| Progressive disclosure | references/, workflows/, templates/ | For skills over ~300 lines |
| TOC in references | recommended at >100 lines | Helps Claude navigate |

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])

```yaml
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)

```yaml
---
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)

```markdown
# 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.

```markdown
## 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]