Createskill

Customization

Before executing, check for user customizations at: ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/CreateSkill/

If this directory exists, load and apply any PREFERENCES.md, configurations, or resources found there. These override default behavior. If the directory does not exist, proceed with skill defaults.

🚨 MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)

You MUST send this notification BEFORE doing anything else when this skill is invoked.

1. Send voice notification:

   curl -s -X POST http://localhost:31337/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running the WORKFLOWNAME workflow in the CreateSkill skill to ACTION"}' \
     > /dev/null 2>&1 &

2. Output text notification:

   Running the **WorkflowName** workflow in the **CreateSkill** skill to ACTION...

This is not optional. Execute this curl command immediately upon skill invocation.

CreateSkill

Complete skill development lifecycle: structure (create, validate, canonicalize) + effectiveness (test, improve, optimize triggers). Structural workflows ensure skills follow PAI conventions. Effectiveness workflows — inspired by Anthropic's skill-creator — ensure skills actually work and trigger reliably.

Authoritative Source

Before creating ANY skill, READ: ~/.claude/PAI/DOCUMENTATION/Skills/SkillSystem.md

Canonical example to follow: any well-formed public skill in ~/.claude/skills/ (e.g. Research/SKILL.md, Daemon/SKILL.md, CreateSkill/SKILL.md itself).

Naming Convention — Public vs Private

Skill name encodes its public/private status. There are exactly two valid forms.

The leading underscore is the public-release boundary. Release tooling skips _* skills entirely — they never leave ~/.claude. Public skills (no underscore) are mirrored into the PAI public release and MUST contain only generic, templated content.

Sub-file naming (both public and private skills):

Wrong (NEVER use):

• Skill dirs: createskill, create-skill, CREATE_SKILL (no underscore + caps for public; no kebab/snake for private)
• Files: create.md, update-info.md, SYNC_REPO.md

Choosing public vs private — the decision rule

Ask: "Could this skill be dropped, as-is, into a stranger's `~/.claude/skills/` and just work?"

• Yes → public skill (TitleCase). Body must be generic; user-specific config layers in via PAI/USER/SKILLCUSTOMIZATIONS/<SkillName>/.
• No, because it references my identity, my contacts, my business, my customer, my paid API, my private infra, my domain, my private repo, my partner, or my financial/health/security data → private skill (_ALLCAPS).

When in doubt, build it private first (`_ALLCAPS`). Promoting `_FOO` → `Foo` later is easy. Discovering a public skill leaks your life is permanent.

---

Public Release Readiness (MANDATORY)

Public skills (`TitleCase`) ship to the world. Private skills (`_ALLCAPS`) never leave the local repo. Sensitivity is decided by skill name, not by per-file scrubbing at share-time.

The Bright Line

Public skill (`TitleCase`) — content rule:

ONLY templated, safe, public, ready content. Period.

• ✅ Generic instructions any PAI user could follow
• ✅ Templated patterns with placeholders for user-specific values
• ✅ Public API references and dependencies on public tools
• ❌ Real names (people, products, companies, customers)
• ❌ Real domains, hostnames, IPs, internal URLs
• ❌ API keys, tokens, credentials, session cookies, OAuth secrets — even example-looking ones
• ❌ Private repo paths or references (github.com/<org>/<private-repo>)
• ❌ Customer data, customer-specific workflows, customer engagement context
• ❌ First-person war stories tied to a specific incident, project, or person
• ❌ User-specific filesystem paths (/Users/<name>/..., /home/<name>/...)
• ❌ Identity-bound preferences (DA name, principal name, partner name, pet name, financial figures, health data)

Private skill (`_ALLCAPS`) — content rule:

Anything goes. Real names, real domains, real customers, real credentials-by-reference (env var names, never values), real war stories, real internal infra. The underscore IS the safety boundary. These skills are excluded from release tooling.

The Decision Test

When you find yourself wanting to write any of the following into a skill body, that skill MUST be _ALLCAPS:

If none of the above apply and the skill is fully generic — it can be TitleCase (public).

Where Personal Layering Goes for Public Skills

A public skill can be made user-specific at runtime via ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/<SkillName>/PREFERENCES.md. The skill body stays generic; the user's customization file overlays per-instance context. Use this when a skill is fundamentally generic but benefits from per-user tweaks (preferred voice, default formats, personal taste).

Do not use SKILLCUSTOMIZATIONS to smuggle private content into a public skill. If the skill requires private context to function (real customer name, real API account, real internal infra), it is a private skill — name it _ALLCAPS and stop.

Allowed in Public Skills

• Generic ~/ paths (~/.claude/skills/, ~/Projects/<tool>/) — resolve per-user
• Public repo URLs for tools the skill depends on
• Public API endpoints that are conventions, not secrets (e.g., localhost:31337/notify)
• Example values clearly marked as placeholders (<url>, <SESSION_ID>, test@example.com)
• Generic env var names (never values): STRIPE_API_KEY, OPENAI_API_KEY

Pre-Flight Grep (Public Skills Only)

Before shipping or modifying any TitleCase skill, run:

rg -i "<your-name>|<your-org>|<your-product>|<your-domain>|/Users/[a-z]+/" ~/.claude/skills/<SkillName>/

Zero matches = ready for public release. Any match = either scrub it, move it to SKILLCUSTOMIZATIONS, or rename the skill to _ALLCAPS and stop pretending it's public. `_ALLCAPS` skills are exempt from this grep — they are private by design.

---

Flat Folder Structure (MANDATORY)

CRITICAL: Keep folder structure FLAT - maximum 2 levels deep.

The Rule

Maximum depth: skills/SkillName/Category/

✅ ALLOWED (2 levels max)

skills/SkillName/SKILL.md                    # Skill root
skills/SkillName/Workflows/Create.md         # Workflow - one level deep - GOOD
skills/SkillName/Tools/Manage.ts             # Tool - one level deep - GOOD
skills/SkillName/QuickStartGuide.md          # Context file - in root - GOOD
skills/SkillName/Examples.md                 # Context file - in root - GOOD

❌ FORBIDDEN (Too deep OR wrong location)

skills/SkillName/Resources/Guide.md              # Context files go in root, NOT Resources/
skills/SkillName/Docs/Examples.md                # Context files go in root, NOT Docs/
skills/SkillName/Workflows/Category/File.md      # THREE levels - NO
skills/SkillName/Templates/Primitives/File.md    # THREE levels - NO
skills/SkillName/Tools/Utils/Helper.ts           # THREE levels - NO

Allowed Subdirectories

These subdirectories are allowed:

• Workflows/ - Execution workflows ONLY
• Tools/ - Executable scripts/tools ONLY
• References/ - Extended reference material for large skills (API docs, detailed guides)

Context files (documentation, guides, references) go in the skill ROOT or in References/.

When to use References/: When SKILL.md exceeds ~500 lines and has substantial reference content (API signatures, detailed examples, troubleshooting guides). Keep SKILL.md as a routing guide; move encyclopedic content to References/.

Why

1. Discoverability - Easy to find files 2. Simplicity - Less navigation overhead 3. Speed - Faster file operations 4. Consistency - Every skill follows same pattern

If you need to organize many workflows, use clear filenames instead of subdirectories:

See: ~/.claude/PAI/DOCUMENTATION/Skills/SkillSystem.md (Flat Folder Structure section)

---

Dynamic Loading Pattern (Large Skills)

For skills with SKILL.md > 100 lines: Use dynamic loading to reduce context on skill invocation.

How Loading Works

Session startup: Only frontmatter loads for routing Skill invocation: Full SKILL.md loads Context files: Load only when workflows reference them

The Pattern

SKILL.md = Minimal (30-50 lines) - loads on skill invocation

• YAML frontmatter with triggers
• Brief description
• Workflow routing table
• Quick reference
• Pointers to context files

Additional .md files = Context files - SOPs for specific aspects (loaded on-demand)

• These are Standard Operating Procedures, not just documentation
• They provide specific handling instructions
• Can reference Workflows/, Tools/, etc.

🚨 CRITICAL: NO Context/ Subdirectory 🚨

NEVER create Context/ or Docs/ subdirectories.

Additional .md files ARE the context files. They live directly in skill root.

WRONG:

skills/Art/
├── SKILL.md
└── Context/              ❌ NEVER CREATE THIS
    └── Aesthetic.md

CORRECT:

skills/Art/
├── SKILL.md
├── Aesthetic.md          ✅ Context file in skill root
├── Examples.md           ✅ Context file in skill root
└── Tools.md              ✅ Context file in skill root

The skill directory IS the context.

Example Structure

skills/Art/
├── SKILL.md              # 40 lines - minimal routing
├── Aesthetic.md          # Context file - SOP for aesthetic
├── Examples.md           # Context file - SOP for examples
├── Tools.md              # Context file - SOP for tools
├── Workflows/            # Workflows
│   └── Essay.md
└── Tools/                # CLI tools
    └── Generate.ts

Minimal SKILL.md Template

---
name: SkillName
description: Create, test, and optimize PAI skills — scaffolding, effectiveness testing, description optimization. USE WHEN create skill, new skill, validate skill, test skill, improve skill, optimize description.
---

# SkillName

Brief description.

## Workflow Routing

| Trigger | Workflow |
|---------|----------|
| "trigger" | `Workflows/WorkflowName.md` |

## Quick Reference

**Key points** (3-5 bullet points)

**Full Documentation:**
- Detail 1: `SkillSearch('skillname detail1')` → loads Detail1.md
- Detail 2: `SkillSearch('skillname detail2')` → loads Detail2.md

When To Use

✅ Use dynamic loading for:

• SKILL.md > 100 lines
• Multiple documentation sections
• Extensive API reference
• Detailed examples

❌ Don't use for:

• Simple skills (< 50 lines)
• Pure utility wrappers (use PAI/TOOLS.md instead)

Benefits

• Token Savings: 70%+ reduction on skill invocation (when full docs not needed)
• Organization: SKILL.md = routing, context files = SOPs for specific aspects
• Efficiency: Workflows load only what they actually need
• Maintainability: Easier to update individual sections

See: ~/.claude/PAI/DOCUMENTATION/Skills/SkillSystem.md (Dynamic Loading Pattern section)

---

Workflow Routing

Structure Workflows (scaffolding and conventions)

Effectiveness Workflows (testing and optimization)

Skill Types (Choose Before Building)

Before creating any skill, identify which of the 9 types it is (from Anthropic's internal skill taxonomy, Thariq Shihipar, Mar 2026). The type shapes structure and testing decisions.

Skill Writing Guidance

When writing or improving skill instructions, follow these principles from Anthropic's skill-creator methodology and Thariq Shihipar's "Lessons from Building Claude Code" (Mar 2026):

Core Principles

• Don't state the obvious. Claude is competent at programming and knows codebases. Focus on information that breaks Claude's default patterns — things it gets wrong without guidance. Test: "Would Claude do this wrong without being told?" If not, remove it.
• Explain the why, not just the what. Models with good theory of mind + clear reasoning outperform models with rigid constraints. Instead of "ALWAYS use 3 bullets", explain why bullets matter for the audience.
• Keep it lean. The context window is a public good. Remove instructions that don't improve output. If test transcripts show the agent wasting time on unproductive steps, cut them. SKILL.md should be under 500 lines.
• Generalize, don't overfit. Fix underlying patterns, not specific test failures. The skill will be used on many prompts beyond your test set.
• Bundle repeated work. If test agents all independently wrote similar helper scripts, add that script to Tools/ so every future invocation benefits.
• Set appropriate degrees of freedom. Match specificity to task fragility. Database migrations need exact commands; code reviews need general direction.
• Don't over-constrain. Skills are reused heavily. Avoid overly specific instructions. Provide needed information but leave flexibility for different contexts.

Description Best Practices

• Descriptions are for models, not humans. The description is injected into the system prompt. Claude reads it to decide whether to invoke the skill.
• Descriptions should be slightly pushy. Models tend to undertrigger. Name specific scenarios even if the user might not explicitly mention the skill.
• Include negative triggers for confusable skills. Add "NOT FOR" clauses when skills share vocabulary: "NOT FOR web pentesting (use WebAssessment)".
• Undertriggering signals: Skill doesn't load when it should, users manually invoking it.
• Overtriggering signals: Skill loads for irrelevant queries, users disabling it.

Gotchas Section (MANDATORY)

Every skill MUST have a ## Gotchas section after the workflow routing table. Thariq: "The highest information density in any Skill comes from gotchas sections."

Populate with:

• API quirks Claude doesn't know about
• Common mistakes observed during usage
• Ordering/sequencing requirements that aren't obvious
• Edge cases that cause silent failures

Gotchas accumulate over time. After every skill failure, add the lesson.

BPE (Bitter-Pilled Engineering) Check

Before finalizing any skill, ask: "Would a smarter model make this skill unnecessary?"

• Anti-fragile (keep): Verification harnesses, data pipelines, tool wrappers, accumulated gotchas, deterministic scripts
• Fragile (question): CoT orchestrators, format parsers, retry cascades, elaborate reasoning scaffolding

Focus skills on knowledge Claude can't derive (failure modes, API quirks), tools Claude can't replicate (API calls, automation), and workflows that benefit from consistency.

Progressive Disclosure (from Anthropic)

Three levels of information loading — use this to manage large skills: 1. Level 1 (YAML frontmatter): Always in system prompt. Triggering info only. 2. Level 2 (SKILL.md body): Loaded when skill is invoked. Routing + key guidance. 3. Level 3 (Reference files): Root-level .md files or References/ subdirectory loaded on demand.

Tell Claude what files exist; it will read them when appropriate. SKILL.md should be under 500 lines — if over, extract detailed content to reference files.

Testing Best Practices (from Anthropic)

Three testing levels for skills: 1. Manual testing — Run queries and observe behavior 2. Scripted testing — Automate test cases (use TestSkill workflow) 3. Programmatic testing — Build evaluation suites (use Evals skill)

Evaluation-driven development: Define what "this skill working" looks like before building the skill. Iterate on a single challenging task until Claude succeeds, then extract the winning approach.

On-Demand Hook Pattern (from Anthropic)

Skills can include hooks that activate only when invoked, remaining effective for the session:

• /careful — Intercept dangerous commands (rm -rf, DROP TABLE, force-push)
• /freeze — Block edits outside specific directories
• /audit — Log all tool calls for session review

All guidance above derived from Thariq Shihipar's "Lessons from Building Claude Code" (Mar 2026), Anthropic's official skill guide, and platform documentation.

Examples

Example 1: Create a new skill from scratch

User: "Create a skill for managing my recipes"
→ Invokes CreateSkill workflow
→ Reads SkillSystem.md for structure requirements
→ Creates skill directory with TitleCase naming
→ Creates SKILL.md, Workflows/, Tools/
→ Suggests running TestSkill to verify effectiveness

Example 2: Fix an existing skill that's not routing properly

User: "The research skill isn't triggering - validate it"
→ Invokes ValidateSkill workflow
→ Checks SKILL.md against canonical format
→ Verifies TitleCase naming and USE WHEN triggers
→ Reports compliance issues with fixes

Example 3: Test if a skill actually helps

User: "Test the Blogging skill to see if it's effective"
→ Invokes TestSkill workflow
→ Generates 3 realistic test prompts
→ Spawns with-skill and baseline agents in parallel
→ Compares outputs, presents results
→ Iterates with ImproveSkill based on feedback

Example 4: Skill isn't triggering on relevant prompts

User: "The Security skill doesn't trigger when I ask about pentesting"
→ Invokes OptimizeDescription workflow
→ Generates 20 should/shouldn't-trigger queries
→ Tests description accuracy via subagents
→ Rewrites description, re-tests, reports improvement

Example 5: Improve a skill that produces weak output

User: "The research skill output is too verbose — improve it"
→ Invokes ImproveSkill workflow
→ Reads skill + user feedback
→ Diagnoses root cause (over-specified instructions)
→ Rewrites with reasoning instead of rigid MUSTs
→ Suggests TestSkill to verify improvement

Execution Log

After completing any workflow, append a single JSONL entry:

echo '{"ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","skill":"CreateSkill","workflow":"WORKFLOW_USED","input":"8_WORD_SUMMARY","status":"ok|error","duration_s":SECONDS}' >> ~/.claude/PAI/MEMORY/SKILLS/execution.jsonl

Replace WORKFLOW_USED with the workflow executed, 8_WORD_SUMMARY with a brief input description, and SECONDS with approximate wall-clock time. Log status: "error" if the workflow failed.

CanonicalizeSkill Workflow

Purpose: Restructure an existing skill to match the canonical format with proper naming conventions.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the CanonicalizeSkill workflow in the CreateSkill skill to restructure skill"}' \
  > /dev/null 2>&1 &

Running the CanonicalizeSkill workflow in the CreateSkill skill to restructure skill...

---

Step 1: Read the Authoritative Source

REQUIRED FIRST: Read the canonical structure:

~/.claude/PAI/SkillSystem.md

This defines exactly what "canonicalize" means.

---

Step 2: Read the Current Skill

~/.claude/skills/[skill-name]/SKILL.md

Identify what's wrong:

• Multi-line description using |?
• Separate triggers: array in YAML? (OLD FORMAT)
• Separate workflows: array in YAML? (OLD FORMAT)
• Missing USE WHEN in description?
• Workflow routing missing from markdown body?
• Workflow files not using TitleCase?
• Skill directory not using TitleCase?

---

Step 3: Backup

cp -r ~/.claude/skills/[skill-name]/ ~/.claude/History/Backups/[skill-name]-backup-$(date +%Y%m%d)/

Note: Backups go to ~/.claude/History/Backups/, NEVER inside skill directories.

---

Step 4: Enforce TitleCase Naming

CRITICAL: All naming must use TitleCase (PascalCase).

Skill Directory Name

✗ WRONG: createskill, create-skill, create_skill, CREATESKILL
✓ CORRECT: Createskill (or CreateSkill for multi-word)

Workflow File Names

✗ WRONG: create.md, CREATE.md, create-skill.md, create_skill.md
✓ CORRECT: Create.md, UpdateDaemonInfo.md, SyncRepo.md

Reference Doc Names

✗ WRONG: prosody-guide.md, PROSODY_GUIDE.md
✓ CORRECT: ProsodyGuide.md, SchemaSpec.md, ApiReference.md

Tool Names

✗ WRONG: manage-server.ts, MANAGE_SERVER.ts
✓ CORRECT: ManageServer.ts (with ManageServer.help.md)

Rename files if needed:

# Example: rename workflow files
cd ~/.claude/skills/[SkillName]/Workflows/
mv create.md Create.md
mv update-info.md UpdateInfo.md
mv sync_repo.md SyncRepo.md

---

Step 5: Enforce Flat Folder Structure

CRITICAL: Maximum 2 levels deep - `skills/SkillName/Category/`

Check for Nested Folders

Scan for folders deeper than 2 levels:

# Find any folders 3+ levels deep (FORBIDDEN)
find ~/.claude/skills/[SkillName]/ -type d -mindepth 2 -maxdepth 3

❌ Common Violations to Fix

Nested Workflows:

✗ WRONG: Workflows/Company/DueDiligence.md
✓ FIX: Workflows/CompanyDueDiligence.md

Nested Templates:

✗ WRONG: Templates/Primitives/Extract.md
✓ FIX: Move to skills/Prompting/Extract.md (templates belong in Prompting)

Nested Tools:

✗ WRONG: Tools/Utils/Helper.ts
✓ FIX: Tools/Helper.ts (or delete if not needed)

Flatten Procedure

1. Identify nested files: Find any file 3+ levels deep 2. Rename for clarity: Category/File.md → CategoryFile.md 3. Move to parent: Move up one level to proper location 4. Update references: Search for old paths and update

Example:

# Before (3 levels - WRONG)
skills/OSINT/Workflows/Company/DueDiligence.md

# After (2 levels - CORRECT)
skills/OSINT/Workflows/CompanyDueDiligence.md

Rule: If you need to organize many files, use clear filenames NOT subdirectories.

---

Step 6: Convert YAML Frontmatter

From old format (WRONG):

---
name: skill-name
description: |
  What the skill does.

triggers:
  - USE WHEN user mentions X
  - USE WHEN user wants to Y

workflows:
  - USE WHEN user wants to A: Workflows/a.md
  - USE WHEN user wants to B: Workflows/b.md
---

To new format (CORRECT):

---
name: SkillName
description: What the skill does. USE WHEN user mentions X OR user wants to Y. Additional capabilities.
---

Key changes:

• Skill name in TitleCase
• Combine description + triggers into single-line description with USE WHEN
• Remove triggers: array entirely
• Remove workflows: array from YAML (moves to body)

---

Step 6: Add Workflow Routing to Body

Add ## Workflow Routing section in markdown body:

# SkillName

[Description]

## Workflow Routing

**When executing a workflow, output this notification:**

Running WorkflowName in SkillName...

| Workflow | Trigger | File |
|----------|---------|------|
| **WorkflowOne** | "trigger phrase one" | `Workflows/WorkflowOne.md` |
| **WorkflowTwo** | "trigger phrase two" | `Workflows/WorkflowTwo.md` |

## Examples

[Required examples section]

## [Rest of documentation]

Note: Workflow names in routing table must match file names exactly (TitleCase).

---

Step 7: Remove Redundant Routing

If the markdown body already had routing information in a different format, consolidate it into the standard ## Workflow Routing section. Delete any duplicate routing tables or sections.

---

Step 8: Ensure All Workflows Are Routed

List workflow files:

ls ~/.claude/skills/[SkillName]/Workflows/

For EACH file: 1. Verify TitleCase naming (rename if needed) 2. Ensure there's a routing entry in ## Workflow Routing 3. Verify routing entry matches exact file name

---

Step 9: Add Gotchas Section

REQUIRED: Every skill needs a ## Gotchas section after the workflow routing table.

## Gotchas

- [Known failure mode or API quirk]
- [Common mistake Claude makes with this skill]
- [Ordering/sequencing requirement that isn't obvious]

If the skill is new or you don't know specific gotchas yet, add the section with a placeholder:

## Gotchas

_No gotchas documented yet. Add failures here as they're discovered._

Per Anthropic: "The highest information density in any Skill comes from gotchas sections."

---

Step 9a: Add Negative Triggers (if applicable)

If the skill shares vocabulary with other skills, add NOT FOR to the description:

description: ... USE WHEN [triggers]. NOT FOR [confusable alternative (use SkillName instead)].

---

Step 9b: Check BPE Compliance

Review each instruction: does it provide knowledge Claude can't derive on its own? Remove instructions that just tell Claude what it already knows. Focus on information that breaks Claude's default patterns.

---

Step 9c: Check SKILL.md Size

If SKILL.md exceeds 500 lines, extract detailed reference content into:

• Root-level context files (existing PAI pattern)
• References/ subdirectory for extensive reference material

Keep SKILL.md as a concise routing guide.

---

Step 10: Add Examples Section

REQUIRED: Every skill needs an ## Examples section with 2-3 concrete usage patterns.

## Examples

**Example 1: [Common use case]**

User: "[Typical user request]" → Invokes WorkflowName workflow → [What skill does] → [What user gets back]

**Example 2: [Another use case]**

User: "[Different request]" → [Process] → [Output]

Place the Examples section after Workflow Routing.

---

Step 10: Verify

Run checklist:

Naming (TitleCase)

• [ ] Skill directory uses TitleCase (e.g., Blogging, Createskill)
• [ ] All workflow files use TitleCase (e.g., Create.md, UpdateInfo.md)
• [ ] All reference docs use TitleCase (e.g., ProsodyGuide.md)
• [ ] All tool files use TitleCase (e.g., ManageServer.ts)
• [ ] Routing table workflow names match file names exactly

YAML Frontmatter

• [ ] name: uses TitleCase
• [ ] description: is single-line with embedded USE WHEN clause
• [ ] No separate triggers: or workflows: arrays in YAML
• [ ] Description uses intent-based language
• [ ] Description is under 1024 characters

Markdown Body

• [ ] ## Workflow Routing section present
• [ ] Routing uses table format with Workflow, Trigger, File columns
• [ ] All workflow files have routing entries
• [ ] ## Examples section with 2-3 concrete usage patterns

Structure

• [ ] tools/ directory exists (even if empty)
• [ ] Workflows contain ONLY work execution procedures
• [ ] Reference docs live at skill root (not in Workflows/)
• [ ] No backups/ directory inside skill

---

TitleCase Reference

---

Done

Skill now matches the canonical structure from SkillSystem.md with proper TitleCase naming throughout.

CreateSkill Workflow

Create a new skill following the canonical structure with proper TitleCase naming.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the CreateSkill workflow in the CreateSkill skill to create new skill"}' \
  > /dev/null 2>&1 &

Running the CreateSkill workflow in the CreateSkill skill to create new skill...

Step 1: Read the Authoritative Sources

REQUIRED FIRST:

1. Read the skill system documentation: ~/.claude/PAI/DOCUMENTATION/Skills/SkillSystem.md 2. Read a canonical example skill — pick any existing public skill in ~/.claude/skills/ (e.g. Research/SKILL.md, Daemon/SKILL.md) and study its frontmatter, voice notification, workflow routing, and examples sections.

Step 2: Understand the Request

Ask the user: 1. What does this skill do? 2. What should trigger it? 3. What workflows does it need?

Step 2a: Identify Skill Type

Classify the skill using the 9 Anthropic skill types (see Skill Types table in SKILL.md):

The type informs structure decisions — e.g., Type 1 skills are mostly gotchas, Type 7 needs safety gates.

Step 2b: BPE Check

Before building, apply the bitter lesson test: "Would a smarter model make this skill unnecessary?"

• If the skill provides knowledge Claude can't derive (API quirks, org decisions) → proceed
• If the skill provides tools Claude can't replicate (API calls, automation) → proceed
• If the skill just orchestrates Claude's reasoning → question whether it's needed

Step 3: Determine TitleCase Names

All names must use TitleCase (PascalCase).

Wrong naming (NEVER use):

• create-skill, create_skill, CREATESKILL → Use CreateSkill
• create.md, CREATE.md, create-info.md → Use Create.md, CreateInfo.md

Step 4: Create the Skill Directory

mkdir -p ~/.claude/skills/[SkillName]/Workflows
mkdir -p ~/.claude/skills/[SkillName]/Tools

Example:

mkdir -p ~/.claude/skills/_DAEMON/Workflows
mkdir -p ~/.claude/skills/_DAEMON/Tools

Step 5: Create SKILL.md

Follow this exact structure:

---
name: SkillName
description: [What it does]. USE WHEN [intent triggers using OR]. NOT FOR [confusable alternatives]. [Additional capabilities].
---

# SkillName

[Brief description]

## Voice Notification

**When executing a workflow, do BOTH:**

1. **Send voice notification**:

curl -s -X POST http://localhost:31337/notify \ -H "Content-Type: application/json" \ -d '{"message": "Running WORKFLOWNAME in SKILLNAME"}' \

/dev/null 2>&1 &

2. **Output text notification**:

Running WorkflowName in SkillName...

**Full documentation:** `~/.claude/PAI/DOCUMENTATION/Notifications/NotificationSystem.md`

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **WorkflowOne** | "trigger phrase" | `Workflows/WorkflowOne.md` |
| **WorkflowTwo** | "another trigger" | `Workflows/WorkflowTwo.md` |

## Examples

**Example 1: [Common use case]**

User: "[Typical user request]" → Invokes WorkflowOne workflow → [What skill does] → [What user gets back]

**Example 2: [Another use case]**

User: "[Different request]" → [Process] → [Output]

## Gotchas

[Known failure modes, API quirks, common mistakes — accumulate over time]

## [Additional Documentation]

[Any other relevant info]

For large skills (>500 lines): Consider adding a References/ subdirectory for detailed API docs, extensive examples, or troubleshooting guides. Keep SKILL.md as a routing guide.

Step 5b: Public Release Readiness (MANDATORY)

Every skill in `~/.claude/skills/` ships with the PAI public release. Write generic from the start — do not rely on a scrub at release-time.

Required

1. No sensitive content — no API keys, tokens, credentials, private URLs, auth secrets, private data 2. No personal references — no author name, no specific project names, no personal domains, no first-person war stories, no user-specific absolute paths like /Users/<name>/... 3. Generic framing — "someone reports a bug" over "<author-name> reports a bug"; "your web project" over "my UL site"; "a common root cause" over "the H3 root cause"

Where Personal Context Belongs

User-specific preferences, project names, domain lists, and war stories go in ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/<SkillName>/ — the skill body loads these at runtime via the Customization block. This keeps the public skill generic while each PAI user layers their own context.

Pre-Flight Check

Before finalizing, grep the skill for personal refs:

rg -i "danielmiessler|unsupervised|ULAdmin|thesurface|human3|ul\.live|/Users/[a-z]+/" ~/.claude/skills/[SkillName]/

Zero matches = ready. Any match = replace with generic language or move to SKILLCUSTOMIZATIONS/.

Step 6: Create Workflow Files

For each workflow in the routing section:

touch ~/.claude/skills/[SkillName]/Workflows/[WorkflowName].md

Workflow-to-Tool Integration (REQUIRED for workflows with CLI tools)

If a workflow calls a CLI tool, it MUST include intent-to-flag mapping tables.

This pattern translates natural language user requests into appropriate CLI flags:

## Intent-to-Flag Mapping

### Model/Mode Selection

| User Says | Flag | When to Use |
|-----------|------|-------------|
| "fast", "quick", "draft" | `--model haiku` | Speed priority |
| (default), "best", "high quality" | `--model opus` | Quality priority |

### Output Options

| User Says | Flag | Effect |
|-----------|------|--------|
| "JSON output" | `--format json` | Machine-readable |
| "detailed" | `--verbose` | Extra information |

## Execute Tool

Based on user request, construct the CLI command:

\`\`\`bash
bun ToolName.ts \
  [FLAGS_FROM_INTENT_MAPPING] \
  --required-param "value"
\`\`\`

Why this matters:

• Tools have rich configuration via flags
• Workflows should expose this flexibility, not hardcode single patterns
• Users speak naturally; workflows translate to precise CLI

Reference: ~/.claude/PAI/DOCUMENTATION/Tools/CliFirstArchitecture.md (Workflow-to-Tool Integration section)

Examples (TitleCase):

touch ~/.claude/skills/MyDaemon/Workflows/UpdateDaemonInfo.md
touch ~/.claude/skills/MyDaemon/Workflows/UpdatePublicRepo.md
touch ~/.claude/skills/MyBlog/Workflows/Create.md
touch ~/.claude/skills/MyBlog/Workflows/Publish.md

Step 7: Verify TitleCase

Run this check:

ls ~/.claude/skills/[SkillName]/
ls ~/.claude/skills/[SkillName]/Workflows/
ls ~/.claude/skills/[SkillName]/Tools/

Verify ALL files use TitleCase:

• SKILL.md ✓ (exception - always uppercase)
• WorkflowName.md ✓
• ToolName.ts ✓
• ToolName.help.md ✓

Step 8: Final Checklist

Naming (TitleCase)

• [ ] Skill directory uses TitleCase (e.g., Blogging, Daemon)
• [ ] All workflow files use TitleCase (e.g., Create.md, UpdateInfo.md)
• [ ] All reference docs use TitleCase (e.g., ProsodyGuide.md)
• [ ] All tool files use TitleCase (e.g., ManageServer.ts)
• [ ] Routing table workflow names match file names exactly

YAML Frontmatter

• [ ] name: uses TitleCase
• [ ] description: is single-line with embedded USE WHEN clause
• [ ] Description includes NOT FOR clause if skill has confusable neighbors
• [ ] No separate triggers: or workflows: arrays
• [ ] Description uses intent-based language
• [ ] Description is under 1024 characters

Markdown Body

• [ ] ## Voice Notification section present (for skills with workflows)
• [ ] ## Workflow Routing section with table format
• [ ] All workflow files have routing entries
• [ ] ## Gotchas section present with known failure modes
• [ ] ## Examples section with 2-3 concrete usage patterns
• [ ] SKILL.md under 500 lines (extract to References/ or root files if over)

Structure

• [ ] Tools/ directory exists (even if empty)
• [ ] No backups/ directory inside skill
• [ ] References/ used for large skills with extensive reference material

BPE Compliance

• [ ] Skill provides knowledge Claude can't derive on its own
• [ ] No instructions compensating for model limitations
• [ ] Skill type identified (see Skill Types table in SKILL.md)

Public Release Readiness

• [ ] No sensitive content (API keys, tokens, credentials, private URLs)
• [ ] No personal references (author name, specific project names, personal domains, user-specific paths)
• [ ] Generic framing throughout ("someone", "your project", not the author name, "my UL site")
• [ ] Pre-flight grep returns zero matches for personal-ref pattern

CLI-First Integration (for skills with CLI tools)

• [ ] CLI tools expose configuration via flags (see CliFirstArchitecture.md)
• [ ] Workflows that call CLI tools have intent-to-flag mapping tables
• [ ] Flag mappings cover: mode selection, output options, post-processing (where applicable)

Step 9: Suggest Effectiveness Testing

After creating the skill, suggest to the user:

"The skill structure is ready. Want me to test it to see if it actually improves outcomes? I can run it against real prompts and compare with a no-skill baseline using the TestSkill workflow."

If the user agrees, invoke Workflows/TestSkill.md.

If the description needs tuning, suggest Workflows/OptimizeDescription.md.

Done

Skill created following canonical structure with proper TitleCase naming throughout.

ImproveSkill Workflow

Improve an existing skill based on test feedback, user observations, or quality concerns. This is the revision half of the test-iterate loop.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the ImproveSkill workflow in the CreateSkill skill to improve skill quality"}' \
  > /dev/null 2>&1 &

Running the ImproveSkill workflow in the CreateSkill skill to improve skill quality...

---

Step 1: Gather Context

Read all available information:

1. The skill: Read the target SKILL.md and the specific workflow(s) relevant to the feedback 2. Test results (if from TestSkill): Read outputs from MEMORY/WORK/skill-test-[name]/ 3. User feedback: What specific complaints or requests did the user have? 4. Transcripts (if available): How did the agent actually use the skill? Where did it waste time or go wrong?

---

Step 2: Diagnose the Problem

Classify each piece of feedback:

---

Step 3: Apply the Writing Philosophy

When rewriting skill instructions, follow these principles:

Explain the Why, Not Just the What

Today's models are smart. They have good theory of mind and when given clear reasoning, they go beyond rote instructions. Instead of rigid rules, explain the reasoning so the model understands what matters.

Bad:

ALWAYS use exactly 3 bullet points. NEVER exceed 50 words per bullet.
MUST include a header. MUST NOT use passive voice.

Good:

Use bullet points to make key findings scannable — readers are busy executives
who need to absorb the main message in under 30 seconds. Keep bullets concise
(aim for one clear idea each) and lead with the most important finding.

The bad version produces compliant but lifeless output. The good version produces output that genuinely serves the reader, and adapts intelligently to different content.

Keep It Lean

Remove instructions that aren't pulling their weight. Read the test transcripts — if the skill makes the agent spend time on steps that don't improve the output, cut them.

Signs of bloat:

• Steps the agent skips or rushes through
• Instructions that produce the same result whether followed or ignored
• Defensive instructions added "just in case" that never trigger

Generalize, Don't Overfit

You're iterating on a few test cases, but the skill will be used on many different prompts. Rather than adding narrow fixes for specific test failures, understand the underlying pattern and address that.

Bad: "When the input contains a CSV with columns named 'Revenue' and 'Cost', always calculate margin as (Revenue-Cost)/Revenue" Good: "When performing financial calculations, identify the relevant columns by semantic meaning (revenue, cost, margin) rather than exact names, since naming conventions vary"

Bundle Repeated Work

If all test agents independently wrote similar helper scripts or took the same multi-step approach, that's a signal the skill should bundle that script in Tools/. Write it once so every future invocation doesn't reinvent the wheel.

---

Step 4: Make the Changes

1. Edit SKILL.md — Update instructions, description, routing as needed 2. Edit workflows — Revise step-by-step instructions 3. Add Tools/ — If repeated work was identified, create bundled scripts 4. Validate structure — Run through the ValidateSkill checklist mentally:

• TitleCase naming preserved
• Flat folder structure maintained
• YAML frontmatter correct
• Routing table matches files

---

Step 5: Verify and Next Steps

After making changes:

• If coming from TestSkill loop: Return to TestSkill Step 3 to rerun tests with the improved skill. Use a new iteration-[N+1]/ directory.
• If standalone improvement: Suggest running TestSkill to verify the improvements actually help.
• If description changed: Suggest running OptimizeDescription to verify trigger accuracy.

---

Step 4a: Update Gotchas Section

After every skill failure or improvement, update the `## Gotchas` section. This is the highest-value section in any skill — it accumulates institutional knowledge about what goes wrong.

If the skill doesn't have a Gotchas section yet, add one after the workflow routing table.

Gotchas should capture:

• The specific failure that prompted this improvement
• API quirks discovered during testing
• Common mistakes Claude makes with this skill
• Edge cases that cause silent failures

---

Step 4b: BPE Audit

While improving, check each instruction against the bitter lesson test:

"Would a smarter model make this instruction unnecessary?"

• If YES → the instruction is compensating for model limitations. Consider removing it.
• If NO → the instruction provides knowledge Claude genuinely can't derive. Keep it.

Focus improvements on: accumulated failure knowledge (gotchas), tool wrappers (scripts), and workflow consistency — not on telling Claude how to think.

---

Anti-Patterns to Avoid

• Adding more MUSTs — If something isn't working, adding louder instructions rarely helps. Reframe with reasoning instead.
• Overfitting to test cases — Fixes that only help the specific test prompts but break on novel inputs.
• Defensive bloat — Adding instructions for edge cases that will never occur in practice.
• Changing structure instead of content — If the skill's instructions are weak, reorganizing files won't fix that.
• Stating the obvious — Don't add instructions for things Claude already knows. Focus on what breaks its default patterns.
• Model-limitation workarounds — Don't add scaffolding that compensates for model weakness. It becomes dead weight as models improve.

OptimizeDescription Workflow

Optimize a skill's YAML description for accurate triggering — ensuring it fires when it should and doesn't fire when it shouldn't.

The description field in SKILL.md frontmatter is the primary mechanism that determines whether a skill gets invoked. A brilliant skill that never triggers is useless. This workflow systematically tests and improves trigger accuracy.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the OptimizeDescription workflow in the CreateSkill skill to optimize skill triggering"}' \
  > /dev/null 2>&1 &

Running the OptimizeDescription workflow in the CreateSkill skill to optimize skill triggering...

---

Step 1: Read the Current Skill

Read the target skill's SKILL.md and note:

• Current description: field
• What the skill actually does
• What workflows it contains
• What adjacent skills might compete for the same triggers

---

Step 2: Generate Trigger Eval Queries

Create 20 eval queries — a mix of should-trigger (10) and should-not-trigger (10).

Should-Trigger Queries (10)

Think about coverage — different phrasings of the same intent:

• Some formal, some casual
• Cases where the user doesn't name the skill but clearly needs it
• Uncommon use cases the skill handles
• Cases where this skill competes with another but should win

Should-Not-Trigger Queries (10)

The most valuable are near-misses — queries that share keywords or concepts but actually need something different:

• Adjacent domains with overlapping vocabulary
• Ambiguous phrasing where naive keyword matching would trigger but shouldn't
• Tasks that touch on the skill's domain but in a context where another tool is better

Avoid obviously irrelevant queries — "write a fibonacci function" as a negative for a PDF skill tests nothing.

Query Quality

Queries must be realistic — something a user would actually type:

• Include file paths, personal context, specific details
• Mix of lengths and formality levels
• Some with typos or casual speech
• Concrete and specific, not abstract

Bad: "Format data", "Create a chart" Good: "ok so I have this quarterly report from finance (its the xlsx in my downloads, Q4_revenue_final.xlsx) and my manager wants a comparison chart showing this quarter vs last quarter with the variance highlighted"

Save as JSON:

[
  {"query": "realistic user prompt here", "should_trigger": true},
  {"query": "near-miss prompt here", "should_trigger": false}
]

---

Step 3: Review Queries with User

Present the eval set and ask the user to: 1. Remove any unrealistic queries 2. Add edge cases they've encountered 3. Flip any should/shouldn't trigger labels they disagree with

This step matters — bad eval queries lead to bad descriptions.

---

Step 4: Test Current Description

First, collect all skill names and descriptions:

rg '^(name|description):' ~/.claude/skills/*/SKILL.md ~/.claude/skills/*/*/SKILL.md --no-filename 2>/dev/null | head -200

Then spawn a single Agent subagent that evaluates ALL queries at once (batching avoids 20+ separate agent spawns):

You have access to the following skills (name and description only):

[Paste the collected name/description pairs]

For each of the following user messages, decide if you would invoke a skill.
Reply with ONLY a JSON array — one entry per query:

[
  {"query": "...", "verdict": "TRIGGER: SkillName"},
  {"query": "...", "verdict": "NO_TRIGGER"}
]

Do not explain. Just the verdicts.

Queries:
1. [query 1]
2. [query 2]
...

Run this batch twice (2 separate subagent calls, in parallel) for reliability — compare the two runs for consistency.

Score: For should-trigger queries, count how often the correct skill triggered. For should-not-trigger queries, count how often NO_TRIGGER was returned (or a different skill triggered). Calculate accuracy as: correct verdicts / total verdicts. Flag any queries where the two runs disagreed (inconsistent triggering).

---

Step 5: Analyze Failures

Identify which queries failed and why:

• False negatives (should trigger but didn't) — description is missing key phrases or concepts
• False positives (shouldn't trigger but did) — description is too broad or shares vocabulary with the wrong domain
• Confusion with other skills — description competes with another skill's territory

---

Step 6: Improve the Description

Based on the failure analysis, rewrite the description:

• For false negatives: add the missing intent phrases or domain concepts
• For false positives: add specificity to distinguish from adjacent skills
• Keep the USE WHEN clause comprehensive but precise
• Stay under 1024 characters (hard limit from SkillSystem.md)

Writing tips for descriptions:

• Slightly "pushy" is better than conservative — undertriggering is a bigger problem than overtriggering
• Include both what the skill does AND specific contexts for when to use it
• Name the competing skills implicitly by being specific about YOUR domain

---

Step 7: Re-Test and Compare

Run the same eval set against the new description (Step 4 again).

Present before/after:

### Description Optimization Results

**Before:** [old accuracy]%
  - False negatives: [N] ([which queries])
  - False positives: [N] ([which queries])

**After:** [new accuracy]%
  - False negatives: [N] ([which queries])
  - False positives: [N] ([which queries])

**Improvement:** [delta]%

---

Step 8: Iterate or Apply

• If accuracy improved but not satisfactory: Repeat Steps 5-7 (max 3 iterations to avoid overfitting)
• If accuracy is good (>85%): Apply the new description to the skill's SKILL.md
• If accuracy degraded: Revert to previous description and try a different approach

Show the user the final description before applying it.

---

Understanding Skill Triggering

Skills appear in the model's context with name + description. The model decides whether to consult a skill based on that description. Important nuance: models tend to undertrigger — they don't use skills when they'd be useful. This means descriptions should be slightly pushy, naming specific scenarios where the skill should be used even if the user doesn't explicitly ask for it.

Simple, one-step queries may not trigger a skill even with a perfect description, because the model handles them directly. Test prompts should be substantive enough that a skill would genuinely help.

TestSkill Workflow

Test a skill's effectiveness by running it against real prompts and comparing with a no-skill baseline.

Inspired by Anthropic's skill-creator methodology: the only way to know if a skill works is to run it on real prompts and compare outputs with and without the skill.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the TestSkill workflow in the CreateSkill skill to test skill effectiveness"}' \
  > /dev/null 2>&1 &

Running the TestSkill workflow in the CreateSkill skill to test skill effectiveness...

---

Step 1: Identify the Skill Under Test

Read the target skill's SKILL.md:

~/.claude/skills/[path]/SKILL.md

Note the skill's:

• Name and description
• Key workflows and what they do
• Expected behavior changes

---

Step 2: Create Test Prompts

Generate 2-4 realistic test prompts — the kind of thing a real user would actually say that should invoke this skill. Share them with the user for review before running.

Good test prompts are:

• Realistic — something a user would actually type, not an abstract request
• Substantive — complex enough that a skill would actually help (simple one-liners may not trigger skill usage)
• Diverse — cover different aspects of the skill's functionality
• Specific — include concrete details (file paths, names, context) like real requests do

Bad: "Format this data" Good: "I have a CSV in ~/Downloads/q4-sales.csv with revenue in column C and costs in column D — add a profit margin percentage column and highlight any margins below 15%"

---

Step 3: Run Test Prompts (With-Skill + Baseline)

Workspace: MEMORY/WORK/skill-test-[skillname]/iteration-[N]/

For each test prompt, spawn TWO Agent subagents in the same turn so they run in parallel:

With-Skill Agent

You are testing a skill. Read the following skill file FIRST, then use its instructions to accomplish the task.

Skill file: [absolute path to SKILL.md]

Task: [test prompt]

Save your final output to: [workspace]/test-[N]/with-skill/output.md

After completing the task, also save a brief transcript of your approach to: [workspace]/test-[N]/with-skill/transcript.md
Include: what steps you took, what tools you used, any decisions you made.

Baseline Agent (No Skill)

Accomplish this task using your general capabilities. Do NOT read any skill files.

Task: [test prompt]

Save your final output to: [workspace]/test-[N]/baseline/output.md

After completing the task, also save a brief transcript of your approach to: [workspace]/test-[N]/baseline/transcript.md
Include: what steps you took, what tools you used, any decisions you made.

Use run_in_background: true for all agents. Launch all with-skill + baseline pairs at once.

---

Step 4: Compare Results

Once all agents complete, for each test prompt:

1. Read both outputs (with-skill and baseline) 2. Read both transcripts to understand approach differences 3. Assess the delta — did the skill actually help?

Present a comparison to the user for each test:

### Test [N]: "[prompt summary]"

**With Skill:**
- Approach: [how it handled the task]
- Quality: [assessment]

**Baseline (No Skill):**
- Approach: [how it handled the task]
- Quality: [assessment]

**Verdict:** [Skill helped significantly / Skill helped marginally / No meaningful difference / Baseline was better]
**Why:** [specific reasons]

---

Step 5: Collect Feedback

Ask the user: 1. Which outputs did you prefer and why? 2. What did the skill get wrong? 3. What should the skill do differently?

Empty feedback on a test = the user thought it was fine.

---

Step 6: Iterate or Complete

Based on feedback:

• If improvements needed: Invoke the Workflows/ImproveSkill.md workflow with the feedback, then rerun tests into a new iteration-[N+1]/ directory. Compare against the previous iteration.
• If skill looks good: Report the results and suggest running Workflows/OptimizeDescription.md to ensure the skill triggers reliably.
• If skill shows no improvement over baseline: The skill may not be needed for this use case, or needs fundamental rethinking. Discuss with the user.

---

Writing philosophy: When improving skills based on test results, see Workflows/ImproveSkill.md Step 3 for the full guidance (explain the why, keep lean, generalize, bundle repeated work).

UpdateSkill Workflow

Purpose: Add workflows or modify an existing skill while maintaining canonical structure and TitleCase naming.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the UpdateSkill workflow in the CreateSkill skill to modify existing skill"}' \
  > /dev/null 2>&1 &

Running the UpdateSkill workflow in the CreateSkill skill to modify existing skill...

---

Step 1: Read the Authoritative Source

REQUIRED FIRST: Read the canonical structure:

~/.claude/PAI/SkillSystem.md

---

Step 2: Read the Current Skill

~/.claude/skills/[SkillName]/SKILL.md

Understand the current:

• Description (single-line with USE WHEN)
• Workflow routing (in markdown body)
• Existing TitleCase naming

---

Step 3: Understand the Update

What needs to change?

• Adding a new workflow?
• Modifying the description/triggers?
• Updating documentation?

---

Step 4: Make Changes

To Add a New Workflow:

1. Determine TitleCase name:

• ✓ Create.md, UpdateDaemonInfo.md, SyncRepo.md
• ✗ create.md, update-daemon-info.md, SYNC_REPO.md

2. Create the workflow file:

touch ~/.claude/skills/[SkillName]/Workflows/[WorkflowName].md

Example:

touch ~/.claude/skills/_DAEMON/Workflows/UpdatePublicRepo.md

3. Add entry to `## Workflow Routing` section in SKILL.md:

## Workflow Routing

| Workflow | Trigger | File |
|----------|---------|------|
| **ExistingWorkflow** | "existing trigger" | `Workflows/ExistingWorkflow.md` |
| **NewWorkflow** | "new trigger" | `Workflows/NewWorkflow.md` |

4. Write the workflow content

To Update Triggers:

Modify the single-line description in YAML frontmatter:

description: [What it does]. USE WHEN [updated intent triggers using OR]. [Capabilities].

To Add a Tool:

1. Create TitleCase tool file:

touch ~/.claude/skills/[SkillName]/Tools/ToolName.ts
touch ~/.claude/skills/[SkillName]/Tools/ToolName.help.md

2. Ensure Tools/ directory exists:

mkdir -p ~/.claude/skills/[SkillName]/Tools

---

Step 5: Verify TitleCase

After making changes, verify naming:

ls ~/.claude/skills/[SkillName]/Workflows/
ls ~/.claude/skills/[SkillName]/Tools/

All files must use TitleCase:

• ✓ WorkflowName.md
• ✓ ToolName.ts, ToolName.help.md
• ✗ workflow-name.md, tool_name.ts

---

Step 6: Final Checklist

Naming

• [ ] New workflow files use TitleCase
• [ ] New tool files use TitleCase
• [ ] Routing table names match file names exactly

Structure

• [ ] YAML still has single-line description with USE WHEN
• [ ] No separate triggers: or workflows: arrays in YAML
• [ ] Markdown body has ## Workflow Routing section
• [ ] All routes point to existing files
• [ ] New workflow files have routing entries

---

Done

Skill updated while maintaining canonical structure and TitleCase naming.

ValidateSkill Workflow

Purpose: Check if an existing skill follows the canonical structure with proper TitleCase naming.

Voice Notification

curl -s -X POST http://localhost:31337/notify \
  -H "Content-Type: application/json" \
  -d '{"message": "Running the ValidateSkill workflow in the CreateSkill skill to validate skill structure"}' \
  > /dev/null 2>&1 &

Running the ValidateSkill workflow in the CreateSkill skill to validate skill structure...

---

Step 1: Read the Authoritative Source

REQUIRED FIRST: Read the canonical structure:

~/.claude/PAI/DOCUMENTATION/Skills/SkillSystem.md

---

Step 2: Read the Target Skill

~/.claude/skills/[SkillName]/SKILL.md

---

Step 3: Check TitleCase Naming

Skill Directory

ls ~/.claude/skills/ | grep -i [skillname]

Verify TitleCase:

• ✓ Blogging, Daemon, CreateSkill
• ✗ createskill, create-skill, CREATE_SKILL

Workflow Files

ls ~/.claude/skills/[SkillName]/Workflows/

Verify TitleCase:

• ✓ Create.md, UpdateDaemonInfo.md, SyncRepo.md
• ✗ create.md, update-daemon-info.md, SYNC_REPO.md

Tool Files

ls ~/.claude/skills/[SkillName]/Tools/

Verify TitleCase:

• ✓ ManageServer.ts, ManageServer.help.md
• ✗ manage-server.ts, MANAGE_SERVER.ts

---

Step 4: Check YAML Frontmatter

Verify the YAML has:

Single-Line Description with USE WHEN

---
name: SkillName
description: [What it does]. USE WHEN [intent triggers using OR]. [Additional capabilities].
---

Check for violations:

• Multi-line description using | (WRONG)
• Missing USE WHEN keyword (WRONG)
• Separate triggers: array in YAML (OLD FORMAT - WRONG)
• Separate workflows: array in YAML (OLD FORMAT - WRONG)
• name: not in TitleCase (WRONG)

---

Step 5: Check Markdown Body

Verify the body has:

Workflow Routing Section

## Workflow Routing

**When executing a workflow, output this notification:**

Running WorkflowName in SkillName...

| Workflow | Trigger | File |
|----------|---------|------|
| **WorkflowOne** | "trigger phrase" | `Workflows/WorkflowOne.md` |

Check for violations:

• Missing ## Workflow Routing section
• Workflow names not in TitleCase
• File paths not matching actual file names

Examples Section

## Examples

**Example 1: [Use case]**

User: "[Request]" → [Action] → [Result]

Check: Examples section required (WRONG if missing)

Gotchas Section

## Gotchas

[Known failure modes, API quirks, common mistakes]

Check: Gotchas section required (WRONG if missing). This is the highest information density in any skill — Anthropic's internal best practice.

Negative Triggers (for skills with confusable neighbors)

Check: If the skill shares vocabulary with other skills, description should include NOT FOR clause:

description: ... USE WHEN [triggers]. NOT FOR [what this ISN'T for (use SkillName instead)].

Common confusable pairs to check: research-style skills (Research vs investigation skills), security-style skills (assessment vs reconnaissance), publishing-style skills (blog vs newsletter)

---

Step 5a-prelude: Public Release Readiness Check

Every skill ships with the PAI public release. Verify the skill is clean of personal/sensitive content:

rg -i "danielmiessler|unsupervised|ULAdmin|thesurface|human3|ul\.live|/Users/[a-z]+/" ~/.claude/skills/[SkillName]/

Check for violations:

• Hardcoded secrets, API keys, tokens, bearer credentials (zero tolerance)
• Author name or first-person war stories ("the user reports", "the April 2026 incident...")
• Specific project names baked into prose (<product>, <subproduct>, <brand>, etc.) — these belong in SKILLCUSTOMIZATIONS/
• User-specific absolute paths (/Users/<name>/...) — use ~/ instead
• Personal domain names (<author>.example, <product>.example, <brand>.example) — unless the skill is specifically about operating that domain

Zero matches = PASS. Any match = FAIL, recommend moving to ~/.claude/PAI/USER/SKILLCUSTOMIZATIONS/<SkillName>/ or rewriting in generic language.

---

Step 5a: BPE Compliance Check

Apply the bitter lesson test to the skill's instructions:

• [ ] Each instruction provides knowledge Claude can't derive on its own
• [ ] No instructions compensating for model limitations (format enforcement, CoT scaffolding)
• [ ] Deterministic scripts used where possible instead of prompt-based workarounds
• [ ] SKILL.md is under 500 lines (large skills should use References/ or root context files)

---

Step 6: Check Workflow Files

ls ~/.claude/skills/[SkillName]/Workflows/

Verify:

• Every file uses TitleCase naming
• Every file has a corresponding entry in ## Workflow Routing section
• Every routing entry points to an existing file
• Routing table names match file names exactly

---

Step 7: Check Structure

ls -la ~/.claude/skills/[SkillName]/

Verify:

• tools/ directory exists (even if empty)
• No backups/ directory inside skill
• Reference docs at skill root (not in Workflows/)

---

Step 7a: Check CLI-First Integration (for skills with CLI tools)

If the skill has CLI tools in `tools/`:

CLI Tool Configuration Flags

Check each tool for flag-based configuration:

bun ~/.claude/skills/[SkillName]/Tools/[ToolName].ts --help

Verify the tool exposes behavioral configuration via flags:

• Mode flags (--fast, --thorough, --dry-run) where applicable
• Output flags (--format, --quiet, --verbose)
• Resource flags (--model, etc.) if applicable
• Post-processing flags if applicable

Workflow Intent-to-Flag Mapping

For workflows that call CLI tools, check for intent-to-flag mapping tables:

grep -l "Intent-to-Flag" ~/.claude/skills/[SkillName]/Workflows/*.md

Required pattern in workflows with CLI tools:

## Intent-to-Flag Mapping

| User Says | Flag | When to Use |
|-----------|------|-------------|
| "fast" | `--model haiku` | Speed priority |
| (default) | `--model sonnet` | Balanced |

Reference: ~/.claude/PAI/DOCUMENTATION/Tools/CliFirstArchitecture.md

---

Step 8: Report Results

COMPLIANT if all checks pass:

Naming (TitleCase)

• [ ] Skill directory uses TitleCase
• [ ] All workflow files use TitleCase
• [ ] All reference docs use TitleCase
• [ ] All tool files use TitleCase
• [ ] Routing table names match file names

YAML Frontmatter

• [ ] name: uses TitleCase
• [ ] description: is single-line with USE WHEN
• [ ] No separate triggers: or workflows: arrays
• [ ] Description under 1024 characters

Markdown Body

• [ ] ## Workflow Routing section present
• [ ] ## Gotchas section present with known failure modes
• [ ] ## Examples section with 2-3 patterns
• [ ] All workflows have routing entries
• [ ] SKILL.md under 500 lines

Content Quality (Anthropic Best Practices)

• [ ] Description includes NOT FOR clause if confusable with other skills
• [ ] Instructions focus on what breaks Claude's defaults (not stating the obvious)
• [ ] No instructions compensating for model limitations (BPE check)
• [ ] Appropriate degrees of freedom (specific for fragile tasks, flexible for safe ones)

Public Release Readiness

• [ ] No sensitive content (API keys, tokens, credentials, private URLs)
• [ ] No personal references (author name, project names, personal domains, user-specific absolute paths)
• [ ] Pre-flight grep for personal refs returns zero matches
• [ ] Personal/user-specific content (if any) lives in SKILLCUSTOMIZATIONS/, not the skill body

Structure

• [ ] Tools/ directory exists
• [ ] No backups/ inside skill
• [ ] References/ used appropriately for large skills

CLI-First Integration (for skills with CLI tools)

• [ ] CLI tools expose configuration via flags (not hardcoded)
• [ ] Workflows that call CLI tools have intent-to-flag mapping tables
• [ ] Flag mappings cover mode, output, and resource selection where applicable

NON-COMPLIANT if any check fails. Recommend using CanonicalizeSkill workflow.