CreateSkill skill

Mandatory orchestrator for all LifeOS skill work — creating, editing, adding a workflow or tool, renaming, validating, or canonicalizing any skill.

by danielmiessler·MIT license·★ 19,269 Stars on the repo·GitHub ↗

Use now

Files of CreateSkill

danielmiessler/main1 file shown
SKILL.md
Show the full text515 lines

Customization

Before executing, check for user customizations at: ~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/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 LifeOS conventions. Effectiveness workflows — inspired by Anthropic's skill-creator — ensure skills actually work and trigger reliably.

Authoritative Source

Before creating ANY skill, READ: ~/.claude/LIFEOS/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.

Skill type Directory format Example Allowed content
Public TitleCase Blogging, Daemon, CreateSkill Templated, safe, generic, ready for public release
Private _ALLCAPS (underscore prefix, all uppercase) _MYSKILL, _MYINBOX, _MYINFRA Personal-scoped function; body publishable-clean, all sensitive data referenced from LIFEOS/USER/

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 LifeOS public release and MUST contain only generic, templated content.

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

Component Format Example
Workflow files TitleCase.md Create.md, UpdateDaemonInfo.md
Reference docs TitleCase.md ProsodyGuide.md, ApiReference.md
Tool files TitleCase.ts ManageServer.ts
Help files TitleCase.help.md ManageServer.help.md

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 LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<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 LifeOS 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 (2026-07-23 separation directive):

Same publishable-clean standard as public skills. The underscore is still the release boundary (release tooling skips _* — that safety net stays), but it no longer licenses embedding personal content. A private skill's body — SKILL.md, workflows, tools — holds only generic code and instructions; everything sensitive lives under LIFEOS/USER/ and the skill reads it by path:

  • Personal data (corpora, inventories, preferences, registries, state) → LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/ — unless a canonical USER home already owns it (GEAR.md, FINANCES/, TELOS/, CONTACTS.md); then point there, never duplicate.
  • Personal config (your domains, account IDs, repo paths, endpoints) → a Config.md/.yaml in that same CUSTOMIZATIONS dir, loaded by the skill at run time.
  • Credentials → env var names in the skill, values in ~/.claude/.env. Never values, never tokens in URLs.
  • Prose refers to "the principal," never a real name; no home-path literals (~-relative or config-resolved paths only).

Why: a private skill in this state is promotable to public with a rename, the whole tree passes one hygiene gate, and a leak of the skills tree leaks no life data. What makes a skill private is that its FUNCTION is personal-scoped (your inbox, your customer, your infra) — not that its files hold your data.

Enforcement: LIFEOS/TOOLS/SkillHygieneGate.ts (deny-list clean, runs inside /ic) + the SystemFileGuard write gate. A new skill is not done while the gate reports violations on it.

The Decision Test

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

If the skill mentions… Skill must be
A specific person's name (yours, your partner's, your team's, a customer's) _ALLCAPS
A specific product name you own or sell _ALLCAPS
A specific customer or client _ALLCAPS
A specific paid API account, billing realm, or subscription _ALLCAPS
A specific private domain, hostname, internal IP, or VPN _ALLCAPS
A specific private repo, dotfile location, or local infra _ALLCAPS
A specific business process tied to your company _ALLCAPS
A specific financial, health, security, or legal context _ALLCAPS
A specific incident or one-off war story _ALLCAPS
Anything that would be wrong, embarrassing, or unsafe in someone else's ~/.claude/ _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/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<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 CUSTOMIZATIONS/SKILLS 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>, [email protected])
  • Generic env var names (never values): STRIPE_API_KEY, OPENAI_API_KEY
Pre-Flight Gate (ALL Skills — public and private)

Before shipping or modifying ANY skill, run the hygiene gate:

bun ~/.claude/LIFEOS/TOOLS/SkillHygieneGate.ts --skill <SkillName>

It scans against the canonical deny-list (LIFEOS/USER/SECURITY/DENY_LIST.txt — the list is identity DATA, so it lives in the USER tree) plus home-path shapes. Exit 0 = clean. Any violation = move the data to LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/ (or its canonical USER home) and reference it by path. Since 2026-07-23 there is no private-skill exemption — _ALLCAPS decides where a skill ships (nowhere), not what its files may contain.


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/LIFEOS/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 LifeOS 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 LIFEOS/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/LIFEOS/DOCUMENTATION/Skills/SkillSystem.md (Dynamic Loading Pattern section)


Workflow Routing

Structure Workflows (scaffolding and conventions)
Workflow Trigger File
CreateSkill "create a new skill" Workflows/CreateSkill.md
ValidateSkill "validate skill", "check skill" Workflows/ValidateSkill.md
UpdateSkill "update skill", "add workflow" Workflows/UpdateSkill.md
CanonicalizeSkill "canonicalize", "fix skill structure" Workflows/CanonicalizeSkill.md
Effectiveness Workflows (testing and optimization)
Workflow Trigger File
TestSkill "test skill", "does this skill work", "skill not working" Workflows/TestSkill.md
ImproveSkill "improve skill", "skill quality", "fix skill instructions" Workflows/ImproveSkill.md
OptimizeDescription "optimize description", "skill not triggering", "trigger accuracy" Workflows/OptimizeDescription.md

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.

Type Focus Key Structure Example
1. Library/API Reference Gotchas, edge cases Claude gets wrong Lightweight, gotchas-heavy, reference snippets HonoReference, D1Reference
2. Product Validation Test/verify code works State assertions, browser automation, output recording Browser
3. Data Fetching Connect to data systems Credential refs, query patterns, dashboard pointers USMetrics, a business-metrics skill
4. Business Process Automate repetitive workflows Execution logs, consistency tracking a task-tracker skill, a syndication skill
5. Code Scaffolding Generate framework boilerplate Template files, project-aware scripts CreateCLI, CreateSkill
6. Code Quality Enforce standards, review Deterministic scripts, hook integration /simplify, /code-review
7. CI/CD & Deployment Deploy with safety patterns Pre-deploy checks, smoke tests, rollback (gap — needs Deploy skill)
8. Operations Runbooks Map phenomena to diagnostics Phenomenon → tool → query → report a site-health skill
9. Infrastructure Ops Maintenance with safety guardrails Safety gates, audit logging, orphan detection a system-management skill, a dotfiles skill

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.
  • Cut intensifier-only lines. Stating a rule once is the instruction. MANDATORY, CRITICAL, "not optional", and a third restatement add volume, not constraint — the model obeys specificity and code, not emphasis. Delete any line whose only content is shouting a rule stated elsewhere. Watch ## Best Practices / ## Tips sections: they collect default-restating filler ("be thorough", "keep it simple", "validate carefully"). Run the delete-test in Prompting/Standards.md § Signal-to-Noise on every line: cut it, and restore only if you can name the specific non-default behavior it forces.
  • 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.

Ideal-State Prompting (WHAT, not HOW) — MANDATORY authoring style

Write every new skill body and workflow ideal-state style: articulate WHAT a done deliverable looks like (as testable outcomes), the CONSTRAINTS, and the TOOLS — then trust the model to find HOW. Numbered step-lists that choreograph the model's reasoning for open-ended cognitive work are BPE-violating scaffolding: they cap a capable model and rot as models improve. Four keep-classes ARE legitimate HOW and belong in skills: safety-gate, verified-gotcha (this is what ## Gotchas is for), tool-contract (exact invocation recipes in Workflows), output-format-contract. Deterministic Tools (*.ts) are exempt. When writing or improving a skill, cut methodology narration and keep only the ideal state, the constraints, the tools, and the four keep-classes. Full standard: LIFEOS/DOCUMENTATION/Skills/SkillSystem.md § Authoring Standard.

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.

Versioning

Every skill carries its own version: semver in SKILL.md frontmatter (Major.Feature.Patch — the middle number is Feature, not "minor"), independent of the OS version and of other skills. A new skill scaffolds at version: 1.0.0. A skill change is ALSO an OS change — skills/ is part of the core-file surface the LifeOS version system watches — so editing a skill moves both the skill's own version AND (rolled up) the canonical LIFEOS/VERSION. The two lines are separate: the skill's version: is its own lineage; LIFEOS/VERSION is the umbrella. CreateSkill never edits LIFEOS/VERSION itself.

Classify the change so the bump level is right (the SAME rubric applies to the per-skill bump and the roll-up):

  • patch — gotcha added, typo, description tweak, doc sync. No new capability.
  • feature — a new workflow or a new tool (a brand-new skill starts at 1.0.0, not a feature bump on itself). Additive, non-breaking.
  • major — renaming or removing the skill, or breaking its public contract or routing behavior. Human gate: stop and confirm before any major bump; never decide major on your own.

When the per-skill bump fires: at private-sync time, not at edit time. The UpdateKaiRepo ship flow runs BumpSkillVersions.ts — for every skills/<name>/ that changed since the last OS tag it scopes ClassifyChange --path skills/<name> and bumps that skill's version: (major held for confirm), recording each in the SYSTEMUPDATES registry. This catches workflow-body edits that never route through CreateSkill. You do NOT hand-bump version: here; the ship flow owns it. (That ship flow is maintainer machinery and does not ship in the public release — on an installed system without it, hand-bump version: per the semver rubric above as part of your edit.) A skill edit is a private-sync change — never a release cut (staging only) or publish (public repo). Keep those three operations distinct.

Public skills do not carry a separate version line — the release/emit carries each skill's private version: forward unchanged.

(Concrete commands/paths for this install layer in via the Customization block above, if present.)

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

Gotchas

  • This file's own description is at ~1022 chars — 2 under the 1024 cap. Any edit that adds characters to the frontmatter description must re-measure before saving (2026-06-13 audit).
  • Two ## Workflow Routing headers exist in this file — the first (~l.276) is inside the embedded template example, the second (~l.315) is the real one. Header-scanning tools must take the LAST match, not the first.
  • Reading this skill's workflows and executing the steps by hand is the handrolling anti-pattern — skills/CLAUDE.md requires invoking the skill, not imitating it. The skill that mandates Gotchas sections went without one until 2026-06-13; treat checklist items as applying to this skill too.

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/LIFEOS/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.

1---
2name: CreateSkill
3version: 1.1.31
4description: "Mandatory orchestrator for all LifeOS skill work — creating, editing, adding a workflow or tool, renaming, validating, or canonicalizing any skill. Handrolling skill files is forbidden; owns the full lifecycle: scaffold, validate, canonicalize, test, improve. USE WHEN create skill, new skill, make a skill, build a skill, set up a skill, private skill, make a X skill, add a workflow, add a tool, edit/change/update/rename a skill, skill frontmatter, validate skill, check skill, canonicalize, scaffold skill, test skill, improve skill, optimize description, skill not triggering, overtriggering. NOT FOR TypeScript CLI generation (use CreateCLI)."
5---
6 
7## Customization
8 
9**Before executing, check for user customizations at:**
10`~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/CreateSkill/`
11 
12If 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.
13 
14 
15## 🚨 MANDATORY: Voice Notification (REQUIRED BEFORE ANY ACTION)
16 
17**You MUST send this notification BEFORE doing anything else when this skill is invoked.**
18 
191. **Send voice notification**:
20 ```bash
21 curl -s -X POST http://localhost:31337/notify \
22 -H "Content-Type: application/json" \
23 -d '{"message": "Running the WORKFLOWNAME workflow in the CreateSkill skill to ACTION"}' \
24 > /dev/null 2>&1 &
25 ```
26 
272. **Output text notification**:
28 ```
29 Running the **WorkflowName** workflow in the **CreateSkill** skill to ACTION...
30 ```
31 
32**This is not optional. Execute this curl command immediately upon skill invocation.**
33 
34# CreateSkill
35 
36Complete skill development lifecycle: **structure** (create, validate, canonicalize) + **effectiveness** (test, improve, optimize triggers). Structural workflows ensure skills follow LifeOS conventions. Effectiveness workflows — inspired by Anthropic's skill-creator — ensure skills actually work and trigger reliably.
37 
38## Authoritative Source
39 
40**Before creating ANY skill, READ:** `~/.claude/LIFEOS/DOCUMENTATION/Skills/SkillSystem.md`
41 
42**Canonical example to follow:** any well-formed public skill in `~/.claude/skills/` (e.g. `Research/SKILL.md`, `Daemon/SKILL.md`, `CreateSkill/SKILL.md` itself).
43 
44## Naming Convention — Public vs Private
45 
46**Skill name encodes its public/private status. There are exactly two valid forms.**
47 
48| Skill type | Directory format | Example | Allowed content |
49|------------|------------------|---------|-----------------|
50| **Public** | `TitleCase` | `Blogging`, `Daemon`, `CreateSkill` | Templated, safe, generic, ready for public release |
51| **Private** | `_ALLCAPS` (underscore prefix, all uppercase) | `_MYSKILL`, `_MYINBOX`, `_MYINFRA` | Personal-scoped *function*; body publishable-clean, all sensitive data referenced from `LIFEOS/USER/` |
52 
53**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 LifeOS public release and MUST contain only generic, templated content.
54 
55**Sub-file naming (both public and private skills):**
56 
57| Component | Format | Example |
58|-----------|--------|---------|
59| Workflow files | `TitleCase.md` | `Create.md`, `UpdateDaemonInfo.md` |
60| Reference docs | `TitleCase.md` | `ProsodyGuide.md`, `ApiReference.md` |
61| Tool files | `TitleCase.ts` | `ManageServer.ts` |
62| Help files | `TitleCase.help.md` | `ManageServer.help.md` |
63 
64**Wrong (NEVER use):**
65- Skill dirs: `createskill`, `create-skill`, `CREATE_SKILL` (no underscore + caps for public; no kebab/snake for private)
66- Files: `create.md`, `update-info.md`, `SYNC_REPO.md`
67 
68### Choosing public vs private — the decision rule
69 
70Ask: **"Could this skill be dropped, as-is, into a stranger's `~/.claude/skills/` and just work?"**
71 
72- **Yes** → public skill (`TitleCase`). Body must be generic; user-specific config layers in via `LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/`.
73- **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`).
74 
75**When in doubt, build it private first (`_ALLCAPS`). Promoting `_FOO` → `Foo` later is easy. Discovering a public skill leaks your life is permanent.**
76 
77---
78 
79## Public Release Readiness (MANDATORY)
80 
81**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.
82 
83### The Bright Line
84 
85**Public skill (`TitleCase`) — content rule:**
86 
87ONLY templated, safe, public, ready content. Period.
88 
89- ✅ Generic instructions any LifeOS user could follow
90- ✅ Templated patterns with placeholders for user-specific values
91- ✅ Public API references and dependencies on public tools
92- ❌ Real names (people, products, companies, customers)
93- ❌ Real domains, hostnames, IPs, internal URLs
94- ❌ API keys, tokens, credentials, session cookies, OAuth secrets — even example-looking ones
95- ❌ Private repo paths or references (`github.com/<org>/<private-repo>`)
96- ❌ Customer data, customer-specific workflows, customer engagement context
97- ❌ First-person war stories tied to a specific incident, project, or person
98- ❌ User-specific filesystem paths (`/Users/<name>/...`, `/home/<name>/...`)
99- ❌ Identity-bound preferences (DA name, principal name, partner name, pet name, financial figures, health data)
100 
101**Private skill (`_ALLCAPS`) — content rule (2026-07-23 separation directive):**
102 
103Same publishable-clean standard as public skills. The underscore is still the release boundary (release tooling skips `_*` — that safety net stays), but it no longer licenses embedding personal content. A private skill's body — SKILL.md, workflows, tools — holds only generic code and instructions; everything sensitive lives under `LIFEOS/USER/` and the skill reads it by path:
104 
105- Personal data (corpora, inventories, preferences, registries, state) → `LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/` — unless a canonical USER home already owns it (`GEAR.md`, `FINANCES/`, `TELOS/`, `CONTACTS.md`); then point there, never duplicate.
106- Personal config (your domains, account IDs, repo paths, endpoints) → a `Config.md`/`.yaml` in that same CUSTOMIZATIONS dir, loaded by the skill at run time.
107- Credentials → env var *names* in the skill, values in `~/.claude/.env`. Never values, never tokens in URLs.
108- Prose refers to "the principal," never a real name; no home-path literals (`~`-relative or config-resolved paths only).
109 
110Why: a private skill in this state is promotable to public with a rename, the whole tree passes one hygiene gate, and a leak of the skills tree leaks no life data. What makes a skill *private* is that its FUNCTION is personal-scoped (your inbox, your customer, your infra) — not that its files hold your data.
111 
112**Enforcement:** `LIFEOS/TOOLS/SkillHygieneGate.ts` (deny-list clean, runs inside `/ic`) + the SystemFileGuard write gate. A new skill is not done while the gate reports violations on it.
113 
114### The Decision Test
115 
116When you find yourself wanting to write any of the following into a skill body, that skill MUST be `_ALLCAPS`:
117 
118| If the skill mentions… | Skill must be |
119|------------------------|---------------|
120| A specific person's name (yours, your partner's, your team's, a customer's) | `_ALLCAPS` |
121| A specific product name you own or sell | `_ALLCAPS` |
122| A specific customer or client | `_ALLCAPS` |
123| A specific paid API account, billing realm, or subscription | `_ALLCAPS` |
124| A specific private domain, hostname, internal IP, or VPN | `_ALLCAPS` |
125| A specific private repo, dotfile location, or local infra | `_ALLCAPS` |
126| A specific business process tied to your company | `_ALLCAPS` |
127| A specific financial, health, security, or legal context | `_ALLCAPS` |
128| A specific incident or one-off war story | `_ALLCAPS` |
129| Anything that would be wrong, embarrassing, or unsafe in someone else's `~/.claude/` | `_ALLCAPS` |
130 
131If none of the above apply and the skill is fully generic — it can be `TitleCase` (public).
132 
133### Where Personal Layering Goes for Public Skills
134 
135A public skill can be made user-specific at runtime via `~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<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).
136 
137**Do not use CUSTOMIZATIONS/SKILLS 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.
138 
139### Allowed in Public Skills
140 
141- Generic `~/` paths (`~/.claude/skills/`, `~/Projects/<tool>/`) — resolve per-user
142- Public repo URLs for tools the skill depends on
143- Public API endpoints that are conventions, not secrets (e.g., `localhost:31337/notify`)
144- Example values clearly marked as placeholders (`<url>`, `<SESSION_ID>`, `[email protected]`)
145- Generic env var *names* (never values): `STRIPE_API_KEY`, `OPENAI_API_KEY`
146 
147### Pre-Flight Gate (ALL Skills — public and private)
148 
149Before shipping or modifying ANY skill, run the hygiene gate:
150```bash
151bun ~/.claude/LIFEOS/TOOLS/SkillHygieneGate.ts --skill <SkillName>
152```
153 
154It scans against the canonical deny-list (`LIFEOS/USER/SECURITY/DENY_LIST.txt` — the list is identity DATA, so it lives in the USER tree) plus home-path shapes. Exit 0 = clean. Any violation = move the data to `LIFEOS/USER/CUSTOMIZATIONS/SKILLS/<SkillName>/` (or its canonical USER home) and reference it by path. Since 2026-07-23 there is no private-skill exemption — `_ALLCAPS` decides where a skill *ships* (nowhere), not what its files may contain.
155 
156---
157 
158## Flat Folder Structure (MANDATORY)
159 
160**CRITICAL: Keep folder structure FLAT - maximum 2 levels deep.**
161 
162### The Rule
163 
164**Maximum depth:** `skills/SkillName/Category/`
165 
166### ✅ ALLOWED (2 levels max)
167 
168```
169skills/SkillName/SKILL.md # Skill root
170skills/SkillName/Workflows/Create.md # Workflow - one level deep - GOOD
171skills/SkillName/Tools/Manage.ts # Tool - one level deep - GOOD
172skills/SkillName/QuickStartGuide.md # Context file - in root - GOOD
173skills/SkillName/Examples.md # Context file - in root - GOOD
174```
175 
176### ❌ FORBIDDEN (Too deep OR wrong location)
177 
178```
179skills/SkillName/Resources/Guide.md # Context files go in root, NOT Resources/
180skills/SkillName/Docs/Examples.md # Context files go in root, NOT Docs/
181skills/SkillName/Workflows/Category/File.md # THREE levels - NO
182skills/SkillName/Templates/Primitives/File.md # THREE levels - NO
183skills/SkillName/Tools/Utils/Helper.ts # THREE levels - NO
184```
185 
186### Allowed Subdirectories
187 
188**These subdirectories are allowed:**
189- **Workflows/** - Execution workflows ONLY
190- **Tools/** - Executable scripts/tools ONLY
191- **References/** - Extended reference material for large skills (API docs, detailed guides)
192 
193**Context files (documentation, guides, references) go in the skill ROOT or in References/.**
194 
195**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/.
196 
197### Why
198 
1991. **Discoverability** - Easy to find files
2002. **Simplicity** - Less navigation overhead
2013. **Speed** - Faster file operations
2024. **Consistency** - Every skill follows same pattern
203 
204**If you need to organize many workflows, use clear filenames instead of subdirectories:**
205 
206**See:** `~/.claude/LIFEOS/DOCUMENTATION/Skills/SkillSystem.md` (Flat Folder Structure section)
207 
208---
209 
210## Dynamic Loading Pattern (Large Skills)
211 
212**For skills with SKILL.md > 100 lines:** Use dynamic loading to reduce context on skill invocation.
213 
214### How Loading Works
215 
216**Session startup:** Only frontmatter loads for routing
217**Skill invocation:** Full SKILL.md loads
218**Context files:** Load only when workflows reference them
219 
220### The Pattern
221 
222**SKILL.md** = Minimal (30-50 lines) - loads on skill invocation
223- YAML frontmatter with triggers
224- Brief description
225- Workflow routing table
226- Quick reference
227- Pointers to context files
228 
229**Additional .md files** = Context files - SOPs for specific aspects (loaded on-demand)
230- These are Standard Operating Procedures, not just documentation
231- They provide specific handling instructions
232- Can reference Workflows/, Tools/, etc.
233 
234### 🚨 CRITICAL: NO Context/ Subdirectory 🚨
235 
236**NEVER create Context/ or Docs/ subdirectories.**
237 
238Additional .md files ARE the context files. They live **directly in skill root**.
239 
240**WRONG:**
241```
242skills/Art/
243├── SKILL.md
244└── Context/ ❌ NEVER CREATE THIS
245 └── Aesthetic.md
246```
247 
248**CORRECT:**
249```
250skills/Art/
251├── SKILL.md
252├── Aesthetic.md ✅ Context file in skill root
253├── Examples.md ✅ Context file in skill root
254└── Tools.md ✅ Context file in skill root
255```
256 
257**The skill directory IS the context.**
258 
259### Example Structure
260 
261```
262skills/Art/
263├── SKILL.md # 40 lines - minimal routing
264├── Aesthetic.md # Context file - SOP for aesthetic
265├── Examples.md # Context file - SOP for examples
266├── Tools.md # Context file - SOP for tools
267├── Workflows/ # Workflows
268│ └── Essay.md
269└── Tools/ # CLI tools
270 └── Generate.ts
271```
272 
273### Minimal SKILL.md Template
274 
275```markdown
276---
277name: SkillName
278description: Create, test, and optimize LifeOS skills — scaffolding, effectiveness testing, description optimization. USE WHEN create skill, new skill, validate skill, test skill, improve skill, optimize description.
279---
280 
281# SkillName
282 
283Brief description.
284 
285## Workflow Routing
286 
287| Trigger | Workflow |
288|---------|----------|
289| "trigger" | `Workflows/WorkflowName.md` |
290 
291## Quick Reference
292 
293**Key points** (3-5 bullet points)
294 
295**Full Documentation:**
296- Detail 1: `SkillSearch('skillname detail1')` → loads Detail1.md
297- Detail 2: `SkillSearch('skillname detail2')` → loads Detail2.md
298```
299 
300### When To Use
301 
302✅ **Use dynamic loading for:**
303- SKILL.md > 100 lines
304- Multiple documentation sections
305- Extensive API reference
306- Detailed examples
307 
308❌ **Don't use for:**
309- Simple skills (< 50 lines)
310- Pure utility wrappers (use LIFEOS/TOOLS.md instead)
311 
312### Benefits
313 
314- **Token Savings:** 70%+ reduction on skill invocation (when full docs not needed)
315- **Organization:** SKILL.md = routing, context files = SOPs for specific aspects
316- **Efficiency:** Workflows load only what they actually need
317- **Maintainability:** Easier to update individual sections
318 
319**See:** `~/.claude/LIFEOS/DOCUMENTATION/Skills/SkillSystem.md` (Dynamic Loading Pattern section)
320 
321---
322 
323 
324## Workflow Routing
325 
326### Structure Workflows (scaffolding and conventions)
327 
328| Workflow | Trigger | File |
329|----------|---------|------|
330| **CreateSkill** | "create a new skill" | `Workflows/CreateSkill.md` |
331| **ValidateSkill** | "validate skill", "check skill" | `Workflows/ValidateSkill.md` |
332| **UpdateSkill** | "update skill", "add workflow" | `Workflows/UpdateSkill.md` |
333| **CanonicalizeSkill** | "canonicalize", "fix skill structure" | `Workflows/CanonicalizeSkill.md` |
334 
335### Effectiveness Workflows (testing and optimization)
336 
337| Workflow | Trigger | File |
338|----------|---------|------|
339| **TestSkill** | "test skill", "does this skill work", "skill not working" | `Workflows/TestSkill.md` |
340| **ImproveSkill** | "improve skill", "skill quality", "fix skill instructions" | `Workflows/ImproveSkill.md` |
341| **OptimizeDescription** | "optimize description", "skill not triggering", "trigger accuracy" | `Workflows/OptimizeDescription.md` |
342 
343## Skill Types (Choose Before Building)
344 
345Before 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.
346 
347| Type | Focus | Key Structure | Example |
348|------|-------|---------------|---------|
349| 1. Library/API Reference | Gotchas, edge cases Claude gets wrong | Lightweight, gotchas-heavy, reference snippets | HonoReference, D1Reference |
350| 2. Product Validation | Test/verify code works | State assertions, browser automation, output recording | Browser |
351| 3. Data Fetching | Connect to data systems | Credential refs, query patterns, dashboard pointers | USMetrics, a business-metrics skill |
352| 4. Business Process | Automate repetitive workflows | Execution logs, consistency tracking | a task-tracker skill, a syndication skill |
353| 5. Code Scaffolding | Generate framework boilerplate | Template files, project-aware scripts | CreateCLI, CreateSkill |
354| 6. Code Quality | Enforce standards, review | Deterministic scripts, hook integration | /simplify, /code-review |
355| 7. CI/CD & Deployment | Deploy with safety patterns | Pre-deploy checks, smoke tests, rollback | (gap — needs Deploy skill) |
356| 8. Operations Runbooks | Map phenomena to diagnostics | Phenomenon → tool → query → report | a site-health skill |
357| 9. Infrastructure Ops | Maintenance with safety guardrails | Safety gates, audit logging, orphan detection | a system-management skill, a dotfiles skill |
358 
359## Skill Writing Guidance
360 
361When 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):
362 
363### Core Principles
364 
365- **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.
366- **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.
367- **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.
368- **Cut intensifier-only lines.** Stating a rule once is the instruction. `MANDATORY`, `CRITICAL`, "not optional", and a third restatement add volume, not constraint — the model obeys specificity and code, not emphasis. Delete any line whose only content is shouting a rule stated elsewhere. Watch `## Best Practices` / `## Tips` sections: they collect default-restating filler ("be thorough", "keep it simple", "validate carefully"). Run the delete-test in `Prompting/Standards.md` § Signal-to-Noise on every line: cut it, and restore only if you can name the specific non-default behavior it forces.
369- **Generalize, don't overfit.** Fix underlying patterns, not specific test failures. The skill will be used on many prompts beyond your test set.
370- **Bundle repeated work.** If test agents all independently wrote similar helper scripts, add that script to Tools/ so every future invocation benefits.
371- **Set appropriate degrees of freedom.** Match specificity to task fragility. Database migrations need exact commands; code reviews need general direction.
372- **Don't over-constrain.** Skills are reused heavily. Avoid overly specific instructions. Provide needed information but leave flexibility for different contexts.
373 
374### Description Best Practices
375 
376- **Descriptions are for models, not humans.** The description is injected into the system prompt. Claude reads it to decide whether to invoke the skill.
377- **Descriptions should be slightly pushy.** Models tend to undertrigger. Name specific scenarios even if the user might not explicitly mention the skill.
378- **Include negative triggers for confusable skills.** Add "NOT FOR" clauses when skills share vocabulary: `"NOT FOR web pentesting (use WebAssessment)"`.
379- **Undertriggering signals:** Skill doesn't load when it should, users manually invoking it.
380- **Overtriggering signals:** Skill loads for irrelevant queries, users disabling it.
381 
382### Gotchas Section (MANDATORY)
383 
384Every skill MUST have a `## Gotchas` section after the workflow routing table. Thariq: "The highest information density in any Skill comes from gotchas sections."
385 
386Populate with:
387- API quirks Claude doesn't know about
388- Common mistakes observed during usage
389- Ordering/sequencing requirements that aren't obvious
390- Edge cases that cause silent failures
391 
392**Gotchas accumulate over time.** After every skill failure, add the lesson.
393 
394### Ideal-State Prompting (WHAT, not HOW) — MANDATORY authoring style
395 
396**Write every new skill body and workflow ideal-state style: articulate WHAT a done deliverable looks like (as testable outcomes), the CONSTRAINTS, and the TOOLS — then trust the model to find HOW.** Numbered step-lists that choreograph the model's reasoning for open-ended cognitive work are BPE-violating scaffolding: they cap a capable model and rot as models improve. Four keep-classes ARE legitimate HOW and belong in skills: **safety-gate**, **verified-gotcha** (this is what `## Gotchas` is for), **tool-contract** (exact invocation recipes in Workflows), **output-format-contract**. Deterministic Tools (`*.ts`) are exempt. When writing or improving a skill, cut methodology narration and keep only the ideal state, the constraints, the tools, and the four keep-classes. Full standard: `LIFEOS/DOCUMENTATION/Skills/SkillSystem.md` § Authoring Standard.
397 
398### BPE (Bitter-Pilled Engineering) Check
399 
400Before finalizing any skill, ask: **"Would a smarter model make this skill unnecessary?"**
401 
402- **Anti-fragile (keep):** Verification harnesses, data pipelines, tool wrappers, accumulated gotchas, deterministic scripts
403- **Fragile (question):** CoT orchestrators, format parsers, retry cascades, elaborate reasoning scaffolding
404 
405Focus 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.
406 
407### Progressive Disclosure (from Anthropic)
408 
409Three levels of information loading — use this to manage large skills:
4101. **Level 1 (YAML frontmatter):** Always in system prompt. Triggering info only.
4112. **Level 2 (SKILL.md body):** Loaded when skill is invoked. Routing + key guidance.
4123. **Level 3 (Reference files):** Root-level `.md` files or `References/` subdirectory loaded on demand.
413 
414Tell 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.
415 
416### Testing Best Practices (from Anthropic)
417 
418Three testing levels for skills:
4191. **Manual testing** — Run queries and observe behavior
4202. **Scripted testing** — Automate test cases (use TestSkill workflow)
4213. **Programmatic testing** — Build evaluation suites (use Evals skill)
422 
423**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.
424 
425### On-Demand Hook Pattern (from Anthropic)
426 
427Skills can include hooks that activate only when invoked, remaining effective for the session:
428- `/careful` — Intercept dangerous commands (rm -rf, DROP TABLE, force-push)
429- `/freeze` — Block edits outside specific directories
430- `/audit` — Log all tool calls for session review
431 
432*All guidance above derived from Thariq Shihipar's "Lessons from Building Claude Code" (Mar 2026), Anthropic's official skill guide, and platform documentation.*
433 
434## Versioning
435 
436Every skill carries its own `version:` semver in SKILL.md frontmatter (`Major.Feature.Patch` — the middle number is **Feature**, not "minor"), independent of the OS version and of other skills. A new skill scaffolds at `version: 1.0.0`. A skill change is ALSO an OS change — `skills/` is part of the core-file surface the LifeOS version system watches — so editing a skill moves both the skill's own version AND (rolled up) the canonical `LIFEOS/VERSION`. The two lines are separate: the skill's `version:` is its own lineage; `LIFEOS/VERSION` is the umbrella. CreateSkill never edits `LIFEOS/VERSION` itself.
437 
438Classify the change so the bump level is right (the SAME rubric applies to the per-skill bump and the roll-up):
439 
440- **patch** — gotcha added, typo, description tweak, doc sync. No new capability.
441- **feature** — a new workflow or a new tool (a brand-new skill starts at 1.0.0, not a feature bump on itself). Additive, non-breaking.
442- **major** — renaming or removing the skill, or breaking its public contract or routing behavior. Human gate: stop and confirm before any major bump; never decide major on your own.
443 
444**When the per-skill bump fires:** at private-sync time, not at edit time. The `UpdateKaiRepo` ship flow runs `BumpSkillVersions.ts` — for every `skills/<name>/` that changed since the last OS tag it scopes `ClassifyChange --path skills/<name>` and bumps that skill's `version:` (major held for confirm), recording each in the SYSTEMUPDATES registry. This catches workflow-body edits that never route through CreateSkill. You do NOT hand-bump `version:` here; the ship flow owns it. (That ship flow is maintainer machinery and does not ship in the public release — on an installed system without it, hand-bump `version:` per the semver rubric above as part of your edit.) A skill edit is a **private-sync** change — never a release **cut** (staging only) or **publish** (public repo). Keep those three operations distinct.
445 
446Public skills do not carry a separate version line — the release/emit carries each skill's private `version:` forward unchanged.
447 
448(Concrete commands/paths for this install layer in via the Customization block above, if present.)
449 
450## Examples
451 
452**Example 1: Create a new skill from scratch**
453```
454User: "Create a skill for managing my recipes"
455→ Invokes CreateSkill workflow
456→ Reads SkillSystem.md for structure requirements
457→ Creates skill directory with TitleCase naming
458→ Creates SKILL.md, Workflows/, Tools/
459→ Suggests running TestSkill to verify effectiveness
460```
461 
462**Example 2: Fix an existing skill that's not routing properly**
463```
464User: "The research skill isn't triggering - validate it"
465→ Invokes ValidateSkill workflow
466→ Checks SKILL.md against canonical format
467→ Verifies TitleCase naming and USE WHEN triggers
468→ Reports compliance issues with fixes
469```
470 
471**Example 3: Test if a skill actually helps**
472```
473User: "Test the Blogging skill to see if it's effective"
474→ Invokes TestSkill workflow
475→ Generates 3 realistic test prompts
476→ Spawns with-skill and baseline agents in parallel
477→ Compares outputs, presents results
478→ Iterates with ImproveSkill based on feedback
479```
480 
481**Example 4: Skill isn't triggering on relevant prompts**
482```
483User: "The Security skill doesn't trigger when I ask about pentesting"
484→ Invokes OptimizeDescription workflow
485→ Generates 20 should/shouldn't-trigger queries
486→ Tests description accuracy via subagents
487→ Rewrites description, re-tests, reports improvement
488```
489 
490**Example 5: Improve a skill that produces weak output**
491```
492User: "The research skill output is too verbose — improve it"
493→ Invokes ImproveSkill workflow
494→ Reads skill + user feedback
495→ Diagnoses root cause (over-specified instructions)
496→ Rewrites with reasoning instead of rigid MUSTs
497→ Suggests TestSkill to verify improvement
498```
499 
500## Gotchas
501 
502- **This file's own description is at ~1022 chars — 2 under the 1024 cap.** Any edit that adds characters to the frontmatter description must re-measure before saving (2026-06-13 audit).
503- **Two `## Workflow Routing` headers exist in this file** — the first (~l.276) is inside the embedded template example, the second (~l.315) is the real one. Header-scanning tools must take the LAST match, not the first.
504- **Reading this skill's workflows and executing the steps by hand is the handrolling anti-pattern** — `skills/CLAUDE.md` requires invoking the skill, not imitating it. The skill that mandates Gotchas sections went without one until 2026-06-13; treat checklist items as applying to this skill too.
505 
506## Execution Log
507 
508After completing any workflow, append a single JSONL entry:
509 
510```bash
511echo '{"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/LIFEOS/MEMORY/SKILLS/execution.jsonl
512```
513 
514Replace `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.
515 

Discussion

Alternatives

Browser Automation SkillWeb browser automation with AI-optimized snapshots for claude-flow agentsCoding · MITWeb Extract — Structured Data from the Open WebExtract structured JSON from web pages, search engines, and entire sites in ONE call — {title, summary, sections, key_metrics, outgoing_links, author, date, page_type, ...} fields, no second LLM pass to parse HTML. Six endpoints: scrape (single URL), scrape-interactive (JS-rendered pages with click/scroll/type), search (Google SERP + deep-scrape), map (URL discovery), crawl + crawl-status (async recursive crawl). Markdown/raw HTML on request. USE when the user needs page DATA — product pricing/specs, article fields, link graphs, JS-heavy SPAs, Google results with content. Prefer over browser-act (automation/screenshots) and WebFetch (static, no JS, no structured fields). Not for citation-rich research (use deep-research). Trigger (EN): scrape this URL, extract data from page, crawl this site, deep-scrape search results, map a domain's URLs, render this JS page. 触发词:抓取/爬取/网页提取/结构化抽取/搜索带内容/全站爬取/JS 渲染抓取/点击后抓取. Requires ZOODATA_API_KEY (free key: https://zoodata.ai/en/api-keys).Sales & ecommerce · MITAI workflow automation specialistAct as an AI Workflow Automation Specialist, guiding users in automating business processes, optimizing workflows, and integrating AI tools effectively.Infrastructure & ops · CC0-1.0Cyber security character workflowThis is a structured image generation workflow for creating cyber security characters. The workflow includes steps such as facial identity mapping, tactical equipment outfitting, cybernetic enhancements, and environmental integration to produce high-quality, cinematic renders. After uploading your face and filling in the values in the fields, your prompt is ready. NOTE: The sample image belongs to me and my brand; unauthorized use of the sample image is prohibited.Creator · CC0-1.0