Files
skills/public/skill-creation.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

602 lines
35 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>skill-creation</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/skill-creation">
<link rel="alternate" type="text/markdown" href="/skill-creation.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/skill-creation.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>skill-creation</h1><p class="lede">Creating new atomic skills for the skills system</p><h1>Skill Creation</h1>
<p><strong>Scope</strong>: Creating atomic skills, structure, integration with CLAUDE.md, discovery patterns <strong>Lines</strong>: ~400 <strong>Last Updated</strong>: 2025-10-18</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Creating new atomic skills for the skills system</li><li>Refactoring monolithic skills into atomic components</li><li>Documenting specialized knowledge for reuse</li><li>Integrating new skills into CLAUDE.md efficiently</li><li>Establishing skill discovery patterns</li><li>Ensuring skills remain composable and maintainable</li></ul>
<h2>Core Concepts</h2>
<h3>Atomic Skill Principles</h3>
<p><strong>Atomicity</strong>: One skill, one focus</p>
<ul><li>Single domain (e.g., &quot;Postgres query optimization&quot; not &quot;All database skills&quot;)</li><li>Clear scope boundary</li><li>Self-contained knowledge</li><li>Can be read and applied in isolation</li></ul>
<p><strong>Composability</strong>: Skills combine for workflows</p>
<ul><li>Reference related skills</li><li>Support skill chaining (Skill A → Skill B → Skill C)</li><li>Work together for complex tasks</li><li>No circular dependencies</li></ul>
<p><strong>Discoverability</strong>: a name somebody can guess</p>
<p>Two things find a skill and they are not the same thing. An agent <em>matches</em> on the description — so the description says when the skill applies and when it does not. A person <em>types</em> the name — so the name has to be guessable by someone who has never seen it.</p>
<p>Guessable means a closed vocabulary. <code>mcp-builder</code> and <code>skill-creator</code> both exist here, which means neither is guessable: an agent looking for the one that makes a thing has to try both words and hope.</p>
<p><strong>The shape: <code>&lt;subject&gt;-&lt;act&gt;</code>, two words.</strong></p>
<p>One word only where the skill <em>is</em> its subject and there is no act — a product or a standard, like <code>hanzo-base</code> or <code>anti-slop</code>. Never three; a third word is almost always a category, and categories are what the index is for.</p>
<p><strong>The acts. One word each, and no synonyms.</strong></p>
<p>| Act | Use | Never | |---|---|---| | Bring something onto this stack | <code>port</code> | migrate, convert, adopt, copy | | Make one from nothing | <code>build</code> | create, builder, creator, scaffold, generate | | Check one behaves | <code>test</code> | testing, qa, validate, verify | | Judge one&#x27;s quality | <code>review</code> | audit, critique, lint | | Ship one | <code>deploy</code> | deployment, release, publish, ship | | Decide what to do | <code>plan</code> | planning, discovery, research |</p>
<p><code>port</code> rather than <code>copy</code> is not a coin toss. A port keeps what the target system already does right and reproduces the source&#x27;s <em>behaviour and appearance</em>; copying says to take the implementation, which is the thing these skills tell you not to do.</p>
<p><strong>The test before you name it.</strong> Could somebody who knows the rule above, and has never seen your skill, write down its name correctly on the first try? If not, the name is wrong — not the reader.</p>
<ul><li>Category directories (<code>cicd/</code>, <code>infrastructure/</code>) group, they do not name</li><li>Keywords in &quot;When to Use This Skill&quot; are what the matcher reads</li><li>Referenced in _INDEX.md</li></ul>
<p><strong>Efficiency</strong>: Optimal size and structure</p>
<ul><li><strong>Target</strong>: 250-400 lines</li><li><strong>Maximum</strong>: 500 lines (split if larger)</li><li><strong>Minimum</strong>: 150 lines (merge if smaller)</li><li>Scannable sections with clear headers</li></ul>
<h3>Integration Philosophy</h3>
<p><strong>CLAUDE.md stays lean</strong>:</p>
<ul><li>Don&#x27;t list every skill individually</li><li>Use category summaries with counts</li><li>Provide Quick Category Reference for pattern matching</li><li>Target: Keep CLAUDE.md under 800 lines</li></ul>
<p><strong>_INDEX.md is comprehensive</strong>:</p>
<ul><li>Complete skill catalog with tables</li><li>Discovery patterns (by tech, task, domain)</li><li>Skill combination examples (workflows)</li><li>Quick reference for common tasks</li></ul>
<hr>
<h2>Skill Structure Template</h2>
<h3>Required Sections</h3>
<p>Every atomic skill must include:</p>
<pre><code class="lang-markdown"># [Skill Name]
**Scope**: One-line description of what this skill covers
**Lines**: ~[estimated line count]
**Last Updated**: YYYY-MM-DD
## When to Use This Skill
Activate this skill when:
- [Specific trigger 1]
- [Specific trigger 2]
- [Specific trigger 3]
- [Specific trigger 4]
- [Specific trigger 5]
## Core Concepts
### [Concept 1]
**[Sub-concept]**:
- Key point 1
- Key point 2
- Key point 3
### [Concept 2]
[Explanation with code examples where applicable]
---
## Patterns
### [Pattern 1 Name]
</code></pre>
<p>// Code example // With explanatory comments</p>
<pre><code>
**When to use**:
- Condition 1
- Condition 2
### [Pattern 2 Name]
</code></pre>
<p>// Another example</p>
<pre><code>
**Benefits**:
- Benefit 1
- Benefit 2
---
## Quick Reference
### [Reference Table or Command List]
</code></pre>
<p>Command/Pattern | Use Case | Example -------------------|--------------------|--------- [item] | [when to use] | [example]</p>
<pre><code>
### [Key Guidelines]
</code></pre>
<p>✅ DO: [Good practice] ✅ DO: [Good practice] ❌ DON&#x27;T: [Anti-pattern] ❌ DON&#x27;T: [Anti-pattern]</p>
<pre><code>
---
## Anti-Patterns
❌ **[Anti-pattern 1]**: [Why it&#x27;s bad]
✅ [Correct approach]
❌ **[Anti-pattern 2]**: [Why it&#x27;s bad]
✅ [Correct approach]
---
## Related Skills
- `related-skill-1.md` - [How it relates]
- `related-skill-2.md` - [How it relates]
- `related-skill-3.md` - [How it relates]
---
**Last Updated**: YYYY-MM-DD
**Format Version**: 1.0 (Atomic)</code></pre>
<h3>Section Guidelines</h3>
<p><strong>&quot;When to Use This Skill&quot;</strong>:</p>
<ul><li>5-8 specific activation triggers</li><li>Action-oriented (&quot;Implementing X&quot;, &quot;Debugging Y&quot;)</li><li>Helps with skill discovery</li><li>Should match _INDEX.md &quot;Use When&quot; column</li></ul>
<p><strong>&quot;Core Concepts&quot;</strong>:</p>
<ul><li>Foundational knowledge</li><li>Mental models and frameworks</li><li>2-4 major concepts</li><li>Each concept 3-5 sub-points</li></ul>
<p><strong>&quot;Patterns&quot;</strong>:</p>
<ul><li>Practical code examples</li><li>Real-world scenarios</li><li>Copy-paste ready snippets</li><li>Commented for clarity</li></ul>
<p><strong>&quot;Quick Reference&quot;</strong>:</p>
<ul><li>Cheat sheet format</li><li>Tables, lists, command references</li><li>Scannable at a glance</li><li>Emergency lookup section</li></ul>
<p><strong>&quot;Anti-Patterns&quot;</strong>:</p>
<ul><li>Common mistakes</li><li>What NOT to do</li><li>Why it&#x27;s wrong + correct alternative</li><li>Learn from common errors</li></ul>
<p><strong>&quot;Related Skills&quot;</strong>:</p>
<ul><li>3-6 related atomic skills</li><li>How they connect (workflow, dependency, alternative)</li><li>Enables skill composition</li></ul>
<hr>
<h2>Creating a New Skill</h2>
<h3>Step 1: Scope Definition</h3>
<p><strong>Ask these questions</strong>:</p>
<ol><li>What&#x27;s the <strong>single focus</strong> of this skill?</li><li>Can I describe it in <strong>one line</strong>?</li><li>Is it <strong>too broad</strong>? (Split into multiple skills)</li><li>Is it <strong>too narrow</strong>? (Merge with related skill)</li><li>What are <strong>5 triggers</strong> for activating this skill?</li></ol>
<p><strong>Example scoping</strong>:</p>
<ul><li>❌ &quot;Database development&quot; → Too broad</li><li>❌ &quot;PostgreSQL EXPLAIN ANALYZE&quot; → Too narrow</li><li>✅ &quot;Postgres query optimization&quot; → Just right (indexes, EXPLAIN, query rewriting)</li></ul>
<h3>Step 2: Research and Outline</h3>
<p><strong>Gather information</strong>:</p>
<ul><li>Official documentation</li><li>Best practices articles</li><li>Common patterns from experience</li><li>Anti-patterns and gotchas</li></ul>
<p><strong>Create outline</strong>:</p>
<pre><code class="lang-markdown"># [Skill Name]
## Core Concepts (2-4 concepts)
- Concept 1: [Mental model]
- Concept 2: [Key principle]
## Patterns (4-8 patterns)
- Pattern 1: [Common use case]
- Pattern 2: [Alternative approach]
## Quick Reference
- Commands/APIs
- Decision matrix
## Anti-Patterns (3-5)
- Common mistake 1
- Common mistake 2
## Related Skills (3-6)
- Skill A (workflow predecessor)
- Skill B (alternative)
- Skill C (next step)</code></pre>
<h3>Step 3: Write Content</h3>
<p><strong>Writing guidelines</strong>:</p>
<ul><li>Use <strong>active voice</strong> (&quot;Configure X&quot; not &quot;X is configured&quot;)</li><li><strong>Code examples</strong> for every pattern</li><li><strong>Clear comments</strong> in code</li><li><strong>Real-world context</strong> (&quot;When building REST APIs...&quot;)</li><li><strong>Concrete over abstract</strong> (show don&#x27;t tell)</li></ul>
<p><strong>Code example format</strong>:</p>
<pre><code class="lang-typescript">// ❌ Bad: No error handling
async function fetchUser(id: string) {
const response = await fetch(`/api/users/${id}`);
return response.json();
}
// ✅ Good: Proper error handling
async function fetchUser(id: string) {
const response = await fetch(`/api/users/${id}`);
if (!response.ok) {
throw new Error(`Failed to fetch user: ${response.status}`);
}
return response.json();
}</code></pre>
<p><strong>Balance depth vs brevity</strong>:</p>
<ul><li>Go deep on <strong>one topic</strong></li><li>Keep related topics as <strong>references to other skills</strong></li><li>Aim for <strong>250-400 lines</strong></li><li>If over 500 lines → split into 2 skills</li></ul>
<h3>Step 4: Test Readability</h3>
<p><strong>Read through and check</strong>:</p>
<ul><li>[ ] Can I scan this in 2 minutes?</li><li>[ ] Are code examples copy-paste ready?</li><li>[ ] Is Quick Reference section useful?</li><li>[ ] Do headers clearly segment content?</li><li>[ ] Are anti-patterns concrete?</li><li>[ ] Do related skills make sense?</li></ul>
<p><strong>Readability test</strong>:</p>
<ul><li>Remove yourself from the skill for 1 day</li><li>Come back and try to use it cold</li><li>Can you find what you need quickly?</li></ul>
<h3>Step 5: Integration with System</h3>
<p><strong>Add to _INDEX.md</strong>:</p>
<ol><li><strong>Add skill to category table</strong>:</li></ol>
<pre><code class="lang-markdown">| `new-skill.md` | Brief description of use case | ~300 |</code></pre>
<ol><li><strong>Update category workflow section</strong>:</li></ol>
<pre><code class="lang-markdown">**Common workflows:**
- New workflow: `new-skill.md` → `existing-skill.md`</code></pre>
<ol><li><strong>Add to discovery patterns</strong>:</li></ol>
<pre><code class="lang-markdown">**New Category**: Search `new-*.md`, `category-*.md`</code></pre>
<ol><li><strong>Create skill combination example</strong> (if workflow-worthy):</li></ol>
<pre><code class="lang-markdown">### New Workflow Name
1. `skill-1.md` - Purpose
2. `new-skill.md` - Purpose
3. `skill-3.md` - Purpose</code></pre>
<ol><li><strong>Add to Quick Reference Table</strong>:</li></ol>
<pre><code class="lang-markdown">| New task | new-skill.md, related-skill.md | 1→2 |</code></pre>
<ol><li><strong>Update total counts</strong>:</li></ol>
<pre><code class="lang-markdown">**Total Skills**: [new count]
### By Category Breakdown
- [Category]: [new count] skills</code></pre>
<p><strong>Update CLAUDE.md</strong> (Section 9 only):</p>
<ol><li><strong>Update category summary</strong> (if new category):</li></ol>
<pre><code class="lang-markdown">**Advanced Categories** ([new count] skills):
- **New Category** ([count]): Skill 1, Skill 2, Skill 3</code></pre>
<ol><li><strong>Update Quick Category Reference</strong>:</li></ol>
<pre><code class="lang-markdown">New Category: new-*.md ([count]) | category-*.md ([count])</code></pre>
<ol><li><strong>Update discovery patterns</strong> (if new pattern):</li></ol>
<pre><code class="lang-markdown">ls skills/new-*.md
ls skills/category/*.md</code></pre>
<ol><li><strong>Update total in header</strong>:</li></ol>
<pre><code class="lang-markdown">### Skills Catalog ([new total] Total)</code></pre>
<p><strong>DO NOT</strong>:</p>
<ul><li>❌ List individual skills in CLAUDE.md (use summaries)</li><li>❌ Add more than 10 lines to CLAUDE.md per skill</li><li>❌ Duplicate content between CLAUDE.md and _INDEX.md</li><li>❌ Exceed 800 lines in CLAUDE.md</li></ul>
<h3>Step 6: File Organization</h3>
<p><strong>Naming convention</strong>:</p>
<ul><li>Lowercase with hyphens: <code>postgres-query-optimization.md</code></li><li>Technology prefix: <code>postgres-<em>.md</code>, <code>react-</em>.md</code></li><li>Pattern: <code>[tech]-[focus].md</code></li></ul>
<p><strong>Directory structure</strong>:</p>
<pre><code>skills/
api/ # Category directories for cohesion
rest-api-design.md
graphql-schema-design.md
cicd/
github-actions-workflows.md
ci-testing-strategy.md
database/ # Or flat with prefix
postgres-query-optimization.md
postgres-*.md # Or prefixed files at root
react-*.md
skill-creation.md # Meta skills at root
_INDEX.md # Always at root</code></pre>
<p><strong>Category vs flat</strong>:</p>
<ul><li>Use <strong>category directories</strong> for 4+ related skills</li><li>Use <strong>prefix pattern</strong> for 2-3 related skills</li><li>Keep <strong>meta/workflow skills</strong> at root (beads-*, skill-creation)</li></ul>
<hr>
<h2>Integration Checklist</h2>
<p>Before considering a skill &quot;complete&quot;:</p>
<p><strong>Skill file itself</strong>:</p>
<ul><li>[ ] Title matches filename</li><li>[ ] Scope is one clear line</li><li>[ ] Line count is accurate (~actual count)</li><li>[ ] &quot;When to Use This Skill&quot; has 5+ triggers</li><li>[ ] Core Concepts section (2-4 concepts)</li><li>[ ] Patterns section with code examples (4-8 patterns)</li><li>[ ] Quick Reference section (tables/commands)</li><li>[ ] Anti-Patterns section (3-5 patterns)</li><li>[ ] Related Skills section (3-6 skills)</li><li>[ ] Last Updated date is current</li><li>[ ] Format Version is specified</li><li>[ ] Total lines: 250-400 (max 500)</li></ul>
<p><strong>_INDEX.md updates</strong>:</p>
<ul><li>[ ] Added to category table with description</li><li>[ ] Updated category workflow section</li><li>[ ] Added to discovery patterns (if new pattern)</li><li>[ ] Created skill combination example (if applicable)</li><li>[ ] Added to Quick Reference Table (if common task)</li><li>[ ] Updated total skills count</li><li>[ ] Updated category breakdown counts</li></ul>
<p><strong>CLAUDE.md updates</strong> (Section 9 only):</p>
<ul><li>[ ] Updated category summary with new count</li><li>[ ] Updated Quick Category Reference (if needed)</li><li>[ ] Updated discovery patterns (if new pattern)</li><li>[ ] Updated total skills count in header</li><li>[ ] Verified CLAUDE.md still under 800 lines</li><li>[ ] No individual skill descriptions added (summaries only)</li></ul>
<p><strong>Testing</strong>:</p>
<ul><li>[ ] Skill is discoverable via pattern search</li><li>[ ] Skill is scannable (can read in 2-3 minutes)</li><li>[ ] Code examples are copy-paste ready</li><li>[ ] Related skills references are accurate</li><li>[ ] Skill fits into documented workflows</li></ul>
<hr>
<h2>Best Practices</h2>
<h3>Writing Style</h3>
<p><strong>Be concise</strong>:</p>
<pre><code class="lang-markdown">❌ &quot;When you are working on implementing authentication and authorization
for your API endpoints, you should consider using this skill.&quot;
✅ &quot;Implementing API authentication and authorization&quot;</code></pre>
<p><strong>Be specific</strong>:</p>
<pre><code class="lang-markdown">❌ &quot;This helps with databases&quot;
✅ &quot;Optimizing slow Postgres queries with EXPLAIN plans and indexes&quot;</code></pre>
<p><strong>Use examples</strong>:</p>
<pre><code class="lang-markdown">❌ &quot;Configure your settings appropriately&quot;
✅</code></pre>
<p>// Configure connection pool const pool = new Pool({ max: 20, // Maximum connections idleTimeoutMillis: 30000, connectionTimeoutMillis: 2000, });</p>
<pre><code></code></pre>
<h3>Code Examples</h3>
<p><strong>Format consistently</strong>:</p>
<ul><li>Language identifier in code fence</li><li>Comments explaining key lines</li><li>Real-world variable names (not foo/bar)</li><li>Show both bad ❌ and good ✅ patterns</li><li>Keep examples under 30 lines</li></ul>
<p><strong>Bad example</strong>:</p>
<pre><code class="lang-javascript">// No context, unclear purpose
function process(x) {
return x.map(y =&gt; y * 2);
}</code></pre>
<p><strong>Good example</strong>:</p>
<pre><code class="lang-typescript">// Transform user data for API response
interface User {
id: string;
email: string;
password: string; // Never send to client
}
function sanitizeUser(user: User) {
const { password, ...safeUser } = user;
return safeUser; // Only id and email
}</code></pre>
<h3>Organization</h3>
<p><strong>Front-load important info</strong>:</p>
<ol><li>&quot;When to Use This Skill&quot; - Helps discovery</li><li>&quot;Core Concepts&quot; - Mental models first</li><li>&quot;Patterns&quot; - Practical examples</li><li>&quot;Quick Reference&quot; - Emergency lookup</li><li>&quot;Anti-Patterns&quot; - Learn from mistakes</li><li>&quot;Related Skills&quot; - Next steps</li></ol>
<p><strong>Use visual hierarchy</strong>:</p>
<ul><li><code>#</code> for skill title</li><li><code>##</code> for major sections</li><li><code>###</code> for sub-sections</li><li><code><strong>Bold</strong></code> for emphasis</li><li>`<code> </code>code<code> </code>` for commands/filenames</li><li>Horizontal rules <code>---</code> between major sections</li></ul>
<h3>Maintenance</h3>
<p><strong>Keep skills current</strong>:</p>
<ul><li>Update &quot;Last Updated&quot; date when changing content</li><li>Review annually for outdated patterns</li><li>Add new patterns as they emerge</li><li>Archive deprecated patterns to Anti-Patterns</li></ul>
<p><strong>Version control</strong>:</p>
<ul><li>Commit skills to git</li><li>Use descriptive commit messages</li><li>Tag major skill system versions</li><li>Track CLAUDE.md changes separately</li></ul>
<hr>
<h2>Common Patterns</h2>
<h3>Pattern 1: Create Category Skill Set</h3>
<p><strong>Scenario</strong>: Adding 5 skills for new technology (Kubernetes)</p>
<p><strong>Steps</strong>:</p>
<ol><li>Create directory: <code>mkdir skills/kubernetes/</code></li><li>Create 5 skills with consistent naming:</li></ol>
<ul><li><code>kubernetes-basics.md</code></li><li><code>kubernetes-deployments.md</code></li><li><code>kubernetes-services.md</code></li><li><code>kubernetes-security.md</code></li><li><code>kubernetes-troubleshooting.md</code></li></ul>
<ol><li>Add category to _INDEX.md with table</li><li>Update CLAUDE.md Section 9 with category summary</li><li>Add discovery pattern: <code>ls skills/kubernetes/*.md</code></li></ol>
<h3>Pattern 2: Split Monolithic Skill</h3>
<p><strong>Scenario</strong>: Existing skill too large (800 lines)</p>
<p><strong>Steps</strong>:</p>
<ol><li>Identify 2-3 distinct sub-topics</li><li>Create separate skills for each</li><li>Extract content to new files</li><li>Update Related Skills to cross-reference</li><li>Archive old monolithic skill to <code>_archive/</code></li><li>Update _INDEX.md and CLAUDE.md</li></ol>
<p><strong>Example</strong>:</p>
<ul><li>Before: <code>database-complete.md</code> (800 lines)</li><li>After: <code>postgres-query-optimization.md</code>, <code>postgres-migrations.md</code>, <code>postgres-schema-design.md</code></li></ul>
<h3>Pattern 3: Add Skill to Existing Category</h3>
<p><strong>Scenario</strong>: One new skill for existing category</p>
<p><strong>Steps</strong>:</p>
<ol><li>Create skill file in category directory or with prefix</li><li>Add row to _INDEX.md category table</li><li>Update category workflow section if needed</li><li>Increment count in CLAUDE.md category summary</li><li>Update total counts in both files</li></ol>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Monolithic skills</strong>: 1000+ line skills covering entire domains ✅ Split into 3-5 atomic skills (250-400 lines each)</p>
<p>❌ <strong>Listing all skills in CLAUDE.md</strong>: Bloats the main config ✅ Use category summaries and Quick Category Reference</p>
<p>❌ <strong>No discovery patterns</strong>: Skills hard to find ✅ Consistent naming, category directories, _INDEX.md search patterns</p>
<p>❌ <strong>Copy-paste from docs</strong>: Raw documentation dumps ✅ Curated patterns, real-world examples, opinionated best practices</p>
<p>❌ <strong>Missing code examples</strong>: Abstract explanations only ✅ Every pattern has code example with comments</p>
<p>❌ <strong>No Related Skills</strong>: Skills exist in isolation ✅ Link 3-6 related skills for composability</p>
<p>❌ <strong>Inconsistent structure</strong>: Each skill different format ✅ Follow template structure (When/Core/Patterns/Quick/Anti/Related)</p>
<p>❌ <strong>Stale content</strong>: Skills never updated ✅ Review and update annually, track &quot;Last Updated&quot; date</p>
<hr>
<h2>Quick Reference</h2>
<h3>New Skill Checklist</h3>
<pre><code>1. Define scope (one-line description, 5 triggers)
2. Research content (docs, best practices)
3. Create outline (Core/Patterns/Quick/Anti/Related)
4. Write content (250-400 lines, code examples)
5. Test readability (scan in 2 minutes)
6. Add to _INDEX.md (table, workflows, patterns)
7. Update CLAUDE.md Section 9 (summary, counts)
8. Verify CLAUDE.md still &lt; 800 lines
9. Commit to git</code></pre>
<h3>File Structure Quick Copy</h3>
<pre><code class="lang-markdown"># Skill Name
**Scope**: One-line description
**Lines**: ~300
**Last Updated**: 2025-10-18
## When to Use This Skill
- Trigger 1
- Trigger 2
## Core Concepts
### Concept 1
## Patterns
### Pattern 1
## Quick Reference
## Anti-Patterns
## Related Skills
---
**Last Updated**: 2025-10-18
**Format Version**: 1.0 (Atomic)</code></pre>
<h3>CLAUDE.md Impact Budget</h3>
<pre><code>Adding 1 skill to existing category:
_INDEX.md: +1 line (table row)
CLAUDE.md: +0 lines (increment count in summary)
Adding new category (5 skills):
_INDEX.md: +40 lines (section with table)
CLAUDE.md: +2 lines (category summary + quick ref)
Current budget:
CLAUDE.md: 678/800 lines (122 lines remaining)
Can add ~60 skills before hitting limit (at current efficiency)</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><code>beads-workflow.md</code> - Managing skill creation as tracked work</li><li><code>beads-context-strategies.md</code> - Managing context during large skill creation</li><li><code>frontend/nextjs-seo.md</code> - Example of well-structured atomic skill</li><li><code>testing/performance-testing.md</code> - Example of comprehensive patterns section</li><li><code>database/postgres-query-optimization.md</code> - Example of code-heavy skill</li></ul>
<hr>
<p><strong>Last Updated</strong>: 2025-10-18 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/skill-creation.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>