hive-skills 0.1.0

package/assets/skills/converted/skill-creator/composable/presets/optimizing.md

@@ -0,0 +1,160 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# skill-creator: Compiled Skill Bundle (preset: optimizing) (v1.0.0)
+
+All composable mini-skills for `skill-creator` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 00-core.md -->
+
+# Core: Skill Creator — the loop and mindset
+
+Cross-cutting foundation for creating new skills, modifying and improving existing skills, and measuring skill performance. Load the focused minis (see INDEX) for each stage: creating, writing, test cases, running evals, improving, blind comparison, description optimization, packaging, environment-specific mechanics, the vendored scripts, JSON schemas, and the subagent instruction files.
+
+The original skill's frontmatter description (the primary triggering mechanism): "Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy."
+
+## Skill Creator
+
+A skill for creating new skills and iteratively improving them.
+
+At a high level, the process of creating a skill goes like this:
+
+- Decide what you want the skill to do and roughly how it should do it
+- Write a draft of the skill
+- Create a few test prompts and run claude-with-access-to-the-skill on them
+- Help the user evaluate the results both qualitatively and quantitatively
+  - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
+  - Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
+- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
+- Repeat until you're satisfied
+- Expand the test set and try again at larger scale
+
+Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
+
+On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
+
+Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
+
+Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
+
+Cool? Cool.
+
+## Communicating with the user
+
+The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
+
+So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
+
+- "evaluation" and "benchmark" are borderline, but OK
+- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
+
+It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
+
+## The core loop (for emphasis)
+
+Repeating the core loop here for emphasis:
+
+- Figure out what the skill is about
+- Draft or edit the skill
+- Run claude-with-access-to-the-skill on test prompts
+- With the user, evaluate the outputs:
+  - Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
+  - Run quantitative evals
+- Repeat until you and the user are satisfied
+- Package the final skill and return it to the user.
+
+Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
+
+Good luck!
+
+---
+<!-- module: 07-description-optimization.md -->
+
+# Description Optimization
+
+The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
+
+> Note on script paths: the `scripts.run_loop` / `scripts.run_eval` module paths and `assets/eval_review.html` below refer to the vendored source at `skills/sources/anthropic/skill-creator/`. Run them from that directory. See the `scripts-and-references` mini for the full inventory.
+
+## Step 1: Generate trigger eval queries
+
+Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
+
+```json
+[
+  {"query": "the user prompt", "should_trigger": true},
+  {"query": "another prompt", "should_trigger": false}
+]
+```
+
+The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
+
+Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
+
+Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`
+
+For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
+
+For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
+
+The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
+
+## Step 2: Review with user
+
+Present the eval set to the user for review using the HTML template:
+
+1. Read the template from `assets/eval_review.html`
+2. Replace the placeholders:
+   - `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
+   - `__SKILL_NAME_PLACEHOLDER__` → the skill's name
+   - `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
+3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
+4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
+5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)
+
+This step matters — bad eval queries lead to bad descriptions.
+
+## Step 3: Run the optimization loop
+
+Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
+
+Save the eval set to the workspace, then run in the background:
+
+```bash
+python -m scripts.run_loop \
+  --eval-set <path-to-trigger-eval.json> \
+  --skill-path <path-to-skill> \
+  --model <model-id-powering-this-session> \
+  --max-iterations 5 \
+  --verbose
+```
+
+Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
+
+While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
+
+This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
+
+## How skill triggering works
+
+Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
+
+This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
+
+## Step 4: Apply the result
+
+Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
+
+---
+<!-- module: 08-packaging.md -->
+
+# Package and Present (only if `present_files` tool is available)
+
+Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
+
+```bash
+python -m scripts.package_skill <path/to/skill-folder>
+```
+
+After packaging, direct the user to the resulting `.skill` file path so they can install it.
+
+> Note on script paths: `scripts.package_skill` refers to the vendored source at `skills/sources/anthropic/skill-creator/scripts/package_skill.py`. See the `scripts-and-references` mini for the full inventory. The `package_skill.py` script works anywhere with Python and a filesystem.

package/assets/skills/converted/skill-creator/composable/presets.json

@@ -0,0 +1,5 @@
+{
+  "authoring": ["00", "01", "02", "03"],
+  "evaluating": ["00", "04", "11", "12", "13", "14"],
+  "optimizing": ["00", "07", "08"]
+}

package/assets/skills/meta/ccs-skill-creator/composable/BUNDLE.md

@@ -0,0 +1,465 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# ccs-skill-creator: Compiled Skill Bundle (v1.0.0)
+
+All composable mini-skills for `ccs-skill-creator` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 00-core.md -->
+
+# CCS Skill Creator: Core
+
+## What CCS is
+
+Compiled Composable Skills (CCS) packages an agent skill as small
+authored markdown **minis** (one subtopic each), a knowledge-free **INDEX** that
+lists them with "load when" hints, an optional always-loaded **00-core** holding
+cross-cutting traps, and a tool-compiled **BUNDLE.md** (the deterministic
+concatenation of every mini) plus optional named **presets/**. The minis are the
+only source of truth; INDEX, BUNDLE, and presets are derived artifacts. The
+payoff: a task loads only the slice it needs, quality stays at least as high as a
+monolith, and every packaging choice is auditable. You build and check skills
+with one stdlib CLI, `tools/hive.py` (subcommands `compile`, `lint`, `parity`,
+`report`). This skill is itself authored in CCS format: the layout you are
+reading is the layout you produce.
+
+## Loading policy (how you consume any CCS skill, including this one)
+
+Read the INDEX first. Load `00-core` if the index marks one. Estimate coverage
+`k/N` = (minis relevant to the task) / (total minis). If `k/N` < ~0.6, load the
+`k` relevant minis individually. If `k/N` ≥ ~0.6, load `BUNDLE.md` (or a matching
+`presets/*.md`) in one read. Never both fan out to subagents and load the whole
+bundle for the same task.
+
+## The two iron rules
+
+1. **The index is a menu, not a meal.** `INDEX.md` carries none of the
+   skill's content, only mini filenames, terse descriptors, and "load when"
+   conditions. Any knowledge a mini needs in order to be applied lives *in the
+   mini*, never in the index.
+2. **Conversion is repackaging, never summarization.** Moving a skill into CCS
+   moves content between containers; it must not shrink it. Every fact,
+   threshold, table, and worked example survives verbatim-equivalent in some
+   mini. Runtime tokens are saved only by *selection* (load fewer minis) and
+   *dedup* (preamble shared across minis factored once into `00-core`), never by
+   cutting content.
+
+## When NOT to use CCS
+
+- **Under ~5k tokens of knowledge** → ship a single `SKILL.md`. The INDEX +
+  00-core scaffolding costs more than selective loading can save.
+- **Knowledge a frontier model already applies well** → write no skill at all.
+  Generic guidance adds tokens and steps without adding quality; a no-skill
+  baseline repeatedly tied or beat skills on tasks inside model competence.
+- **Every task needs the entire skill** → it is one document; just ship the
+  bundle, no selective loading to do.
+
+---
+<!-- module: 01-create-new-skill.md -->
+
+# Create a New CCS Skill From Scratch
+
+Use this when authoring a brand-new skill (no existing source to convert; for
+that see `02-convert-existing-skill.md`). Follow the steps in order. Each step
+lists exact commands and an **Acceptance** bar you must clear before moving on.
+
+## Step 0: Decide whether to write a skill at all
+
+Apply the "When NOT to use CCS" test from `00-core`: skip the skill if it would
+carry under ~5k tokens of content (ship a single `SKILL.md` instead), or if a
+frontier model already handles it well (write nothing). For each candidate piece
+of guidance ask: *"would a strong model reliably do this unprompted?"* If yes,
+cut it. What remains (the traps and non-obvious calls) is your skill.
+
+**Acceptance:** you can name at least a few trap-dense, non-inferable pieces of
+knowledge, and tasks that use it vary in which subtopics they need.
+
+## Step 1: Scope the domain
+
+Define one coherent domain a practitioner would recognize ("code review",
+"financial analysis"), broad enough to have several subtopics but narrow enough
+that any single task touches only some of them. Write down, before slicing:
+
+- the **subtopics** a practitioner distinguishes;
+- the **cross-cutting traps** that apply regardless of subtopic (these become
+  `00-core`);
+- a few **representative tasks** spanning narrow (one subtopic) to broad (most
+  subtopics), to sanity-check your slicing.
+
+**Acceptance:** a written list of subtopics, cross-cutting traps, and 3–5
+representative tasks.
+
+## Step 2: Create the directory layout
+
+A CCS skill lives under `skills/<category>/<domain>/composable/` with exactly this shape:
+
+```
+skills/<category>/<domain>/
+└── composable/
+    ├── INDEX.md          # the menu (you author this)
+    ├── mini/
+    │   ├── 00-core.md    # optional always-load cross-cutting mini
+    │   └── NN-topic.md   # the authored modules (source of truth)
+    ├── BUNDLE.md         # generated by hive.py compile — never hand-write
+    └── presets/          # optional, generated named subsets
+        └── <name>.md
+```
+
+Pick `<category>` by provenance: `authored/` for a skill written directly in CCS
+form, `converted/` for one ported from an existing upstream skill, `meta/` for a
+skill about the CCS framework itself. Create
+`skills/<category>/<domain>/composable/mini/`. Name minis `NN-topic.md` with a
+two-digit ordinal; the ordinal fixes index and bundle order. `00-core.md` MUST
+use ordinal `00`.
+
+**Acceptance:** `mini/` exists; planned filenames chosen.
+
+## Step 3: Slice the minis (one subtopic each)
+
+Aim for roughly 6–12 minis. Rules:
+
+- **One focused subtopic per mini.** If a mini covers two things a task might
+  want separately, split it. If two minis are never useful apart, merge them.
+- **Order for loading.** Put the "start here" method mini first; group related
+  subtopics adjacently.
+
+**Acceptance:** for each representative task from Step 1, you can list which minis
+it should load. If a needed rule falls cleanly into no single mini, re-slice.
+
+## Step 4: Write each mini, self-contained and uncompressed
+
+Every mini MUST be applicable from *its own text plus `00-core`*, never
+"as covered in the performance mini…". Restate the little that is needed; this
+deliberate redundancy is what makes selective loading safe. Each mini MUST start
+with an H1 (`# Title`). Size follows content: typical minis run ~300–700 words,
+longer when the subtopic demands it. **Never thin content to hit a size**: you
+save tokens by *selection*, never by summarizing.
+
+**Acceptance:** every mini has an H1 and reads correctly with only itself +
+`00-core` in context.
+
+## Step 5: Write `00-core.md` (traps only, if warranted)
+
+`00-core` carries *only* cross-cutting traps: guidance relevant more often than
+a task-scoped reader would guess (data-quality/input-validation discipline,
+"prove it before you claim it", "present ranges not points"). Keep it small. It
+is paid on every load, like the index. It states the cross-cutting rule and
+points to the focused mini for depth; it MUST NOT reproduce a subtopic's full
+treatment. If the skill has no genuinely cross-cutting traps, omit `00-core` and
+instead mark the "start here" method mini always-load in the index.
+
+**Acceptance:** `00-core` (if present) is small and holds only cross-cutting
+material, not a subtopic's depth.
+
+## Step 6: Write the INDEX (a knowledge-free menu)
+
+`INDEX.md` is a menu, not a meal (iron rule 1). Under ~200 words. Structure:
+
+1. An H1 title.
+2. The standard loading-policy header (see below), verbatim, right after the H1.
+3. Exactly **one line per mini**, each carrying (a) the mini filename, (b) a
+   terse content descriptor (the nouns a task matches on), and (c) a **"load
+   when"** hint phrased as an *observable task condition*, not a topic
+   restatement.
+
+If `00-core.md` exists, its line MUST be marked **always load** and the header
+tells the reader to load it first.
+
+Standard header (paste verbatim after the H1):
+
+```
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If you judge most of this skill relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+```
+
+Good line: `` - `04-concurrency.md` — Races, shared state, deadlocks, async,
+TOCTOU. Load when code is threaded, async, or shares state.``. Weak (avoid):
+`` - `04-concurrency.md` — About concurrency.`` (no trigger).
+
+**Acceptance:** one index line per mini and one mini per index line (no drift);
+no line carries knowledge; `00-core` marked always-load if present.
+
+## Step 7: Compile and lint, then fix findings
+
+Generate the bundle (and any presets) and check the structure. Run from the repo
+root:
+
+```bash
+python3 tools/hive.py compile skills/<category>/<domain>
+python3 tools/hive.py lint    skills/<category>/<domain>
+```
+
+`compile` writes `BUNDLE.md`: the deterministic concatenation of every mini in
+ordinal order, `00-core` first, each preceded by a `<!-- module: NN-name.md -->`
+marker. Never hand-edit `BUNDLE.md`. Add a preset only for a real recurring
+configuration: `--presets security-audit=00-core,02 quick=00-core,01`. Do not
+generate a combinatorial family of presets speculatively.
+
+`lint` checks: INDEX exists and references each mini exactly once; index word
+budget; no index line reads like knowledge; `00-core` marked always-load; every
+mini nonempty with an H1; frontmatter (if any) valid; `BUNDLE.md` not stale. Fix
+every **FAIL**; resolve **WARN**s or justify them. Re-run `compile` after any
+mini edit so `BUNDLE.md` is never stale.
+
+**Acceptance:** `lint` exits 0 (`… 0 fail`).
+
+## Worked micro-example: a `sql-migrations` skill
+
+1. **Scope.** Domain = writing safe database schema migrations. Subtopics:
+   backward-compatible changes, destructive changes, index/lock behavior,
+   data backfills. Cross-cutting trap: "a migration runs against production data
+   under live traffic, never assume an empty table or a maintenance window."
+2. **Slice.** Four minis: `01-backward-compatible.md`,
+   `02-destructive-changes.md`, `03-locks-and-indexes.md`, `04-backfills.md`,
+   plus `00-core.md` for the live-traffic trap.
+3. **Minis.** `03-locks-and-indexes.md` restates the "add index concurrently to
+   avoid a table lock" rule even though `01` mentions locks in passing, because
+   a task that loads only `03` must not miss it (self-containment).
+4. **Core.** `00-core.md` (~120 words): live-traffic assumption, "expand then
+   contract" pattern, always ship a tested rollback; points to `02` for the
+   destructive-change detail. Marked always-load.
+5. **Index.** Five lines. `` - `03-locks-and-indexes.md` — CONCURRENTLY, lock
+   modes, long-held locks. Load when adding/dropping indexes or altering large
+   tables.``
+6. **Compile & lint.** `python3 tools/hive.py compile skills/sql-migrations`
+   then `lint` → 0 fail. Narrow task "add a nullable column" loads {00-core, 01}
+   (k/N = 0.4 < 0.6, load minis). Broad "review this whole migration set" →
+   k/N ≥ 0.6 → load `BUNDLE.md` in one read.
+
+---
+<!-- module: 02-convert-existing-skill.md -->
+
+# Convert an Existing Skill to CCS
+
+Use this to repackage an existing skill (a monolithic `SKILL.md`, a `SKILL.md`
+plus a `reference/` tree, or a prompt library) into CCS. For a brand-new skill
+with no source, see `01-create-new-skill.md`. The governing rule is iron rule 2:
+**conversion is repackaging, never summarization** (see `00-core`).
+
+## The failure you are avoiding
+
+The `financial-analyst` conversion once decomposed a ~7,000-word source against
+word budgets (250–450 words × ≤11 minis), forcing ~30% compression; token savings
+transferred as predicted but the compressed tail held the judges' deciding
+details and the converted skill *measurably lost quality on both eval tasks*: a
+content loss, not a packaging flaw. That is why the parity gate below is
+mandatory, and why you carry content at **full fidelity with no size caps**.
+
+## Step 1: Inventory the source
+
+Enumerate the source's substantive units: every section/heading, table,
+threshold, worked example, and always-loaded preamble. This list is your parity
+checklist: nothing on it may vanish. Note where the source keeps its knowledge
+(monolith body, reference files, prompt entries) and any always-loaded preamble
+that repeats across files (that repetition is your one legitimate dedup target).
+
+**Acceptance:** a written list of every substantive unit in the source.
+
+## Step 2: Map source structure to CCS elements
+
+| Source structure | Maps to |
+|---|---|
+| Monolith top matter / always-loaded preamble | `00-core` (cross-cutting only) + INDEX framing |
+| Monolith section / heading | one mini (`NN-topic.md`) |
+| `SKILL.md` router / purpose table | `INDEX.md` (add a "load when" hint per entry) |
+| `SKILL.md` always-loaded body | split: cross-cutting → `00-core`; subtopic prose → its mini |
+| `reference/<topic>.md` file | one or more minis (split if coarse) |
+| Prompt-library entry / template | one mini per coherent procedure |
+| Repeated preamble across references | factored once into `00-core` (dedup) |
+| Scripts, fixtures, templates, data | left as-is; referenced from a mini by path |
+| The whole source, recompiled | `BUNDLE.md` (the parity target) |
+
+Two rules of thumb: a coarse reference file (say 2,500 tokens) usually becomes
+**several** minis: one mini reproduces the lost-in-the-middle problem inside a
+single file. And the source's purpose table becomes the INDEX, but you must
+**add** the "load when" hints if the source lacked them; triggers drive expert
+selection.
+
+**Acceptance:** every inventory unit from Step 1 is assigned to a specific mini.
+
+## Step 3: Create the layout and carry content at full fidelity
+
+Create `skills/<category>/<domain>/composable/mini/` (layout identical to a from-scratch
+skill: `INDEX.md`, `mini/00-core.md` + `mini/NN-topic.md`, generated `BUNDLE.md`,
+optional `presets/`). Copy each source unit into its assigned mini **verbatim or
+verbatim-equivalent**. Split coarse references into focused minis (e.g. a DCF
+reference → `04-dcf-projection.md` + `05-terminal-value-sensitivity.md`). Factor
+preamble repeated across three or more source files once into `00-core`. Make
+each mini self-contained (applicable from its own text + `00-core`) and give it
+an H1.
+
+**There are no size caps.** If faithful fidelity needs more room, add minis or
+enlarge them: the fix for "too much content" is *more or larger minis*, never
+tighter prose. Do not compress "to tidy up." Leave scripts/assets untouched and
+reference them from a mini by path.
+
+**Acceptance:** every mini has an H1; every inventory unit is present at full
+fidelity in some mini; only genuine cross-file duplication was removed (and now
+lives once in `00-core`).
+
+## Step 4: Write the INDEX
+
+Turn the source's purpose table into `INDEX.md`: an H1, the standard
+loading-policy header verbatim after it, then one knowledge-free line per mini
+with a filename, terse descriptor, and a **"load when"** observable-condition
+hint. Mark `00-core` **always load** if present. Keep under ~200 words (~300 if
+more than 12 minis). Standard header, pasted verbatim after the H1:
+
+```
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If you judge most of this skill relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+```
+
+## Step 5: Compile, then run the parity gate and lint
+
+Run from the repo root:
+
+```bash
+python3 tools/hive.py compile skills/<category>/<domain>
+python3 tools/hive.py parity  skills/<category>/<domain> <source-dir>
+python3 tools/hive.py lint    skills/<category>/<domain>
+```
+
+`parity` compares the union of your minis against the original source. It reports
+a **token ratio** (mini tokens ÷ source tokens) and lists any source `##`/`###`
+heading with no fuzzy match in the minis (possibly dropped). Acceptance bar:
+
+- Ratio **≥ 85%** is the hard floor (below it, `parity` FAILs and summarization
+  is suspected). **Aim for 95%+**: a faithful conversion loses tokens only to
+  genuine dedup, so the union of minis should be nearly the whole source.
+- The dropped-heading list must be **empty**, or every entry on it explained as
+  genuine duplication now living once in `00-core`. Treat each listed heading as
+  a real gap: open the source section, find where it should live, and restore it
+  into the right mini. Re-run `compile` then `parity` until clean.
+
+`lint` must exit 0 (INDEX/mini/core structural rules, `00-core` marked
+always-load, `BUNDLE.md` not stale). A conversion that cannot pass parity within
+your current mini count needs **more or larger minis, not tighter prose**.
+
+**Acceptance:** `parity` ratio ≥ 85% (target 95%+) with no unexplained dropped
+heading, **and** `lint` exits 0. Only then is the conversion done.
+
+## Edge cases
+
+- **No cross-cutting content in the source** → omit `00-core`; mark the "start
+  here" mini always-load instead. Don't invent core material.
+- **Script-heavy skill** → convert only the knowledge markdown; leave
+  `scripts/`, `assets/`, fixtures exactly as they are and reference them by path.
+- **Source already close to CCS** (fine-grained references with triggers) →
+  conversion is mostly mechanical: rename to `NN-topic.md`, write the INDEX with
+  "load when" hints, compile, parity-check. Still do not compress.
+- **Very large source** that overflows your intended mini count at full
+  fidelity → raise the mini count. Parity outranks any target mini count.
+
+---
+<!-- module: 03-review-and-maintain.md -->
+
+# Review and Maintain a CCS Skill
+
+Use this when changing a skill that already exists in CCS format: editing its
+knowledge, adding a preset, or checking it still conforms. The governing
+discipline is the source/artifact split: `mini/*.md` is the only source of
+truth; `INDEX.md`, `BUNDLE.md`, and `presets/*.md` are derived.
+
+## The maintenance loop (edit minis, recompile, relint)
+
+To change any knowledge:
+
+1. **Edit the mini**, never `BUNDLE.md` or `presets/*.md`. Those are generated;
+   hand-edits are overwritten on the next compile and break the parity guarantee.
+2. **Recompile** so the bundle (and presets) match the minis again:
+
+   ```bash
+   python3 tools/hive.py compile skills/<category>/<domain>
+   ```
+
+3. **Relint** and fix every FAIL:
+
+   ```bash
+   python3 tools/hive.py lint skills/<category>/<domain>
+   ```
+
+   `lint` flags a **stale BUNDLE.md** (`does not match mini/*.md — re-run
+   compile`) whenever a mini changed but the bundle was not regenerated. Note the
+   asymmetry: editing only `INDEX.md` does *not* stale the bundle (the bundle is
+   built from minis, not the index), but it can still break other lint rules
+   (drift, word budget, always-load marking), so relint after any edit.
+
+**Acceptance:** `lint` exits 0 after every change.
+
+## Keep the INDEX in sync
+
+Every mini file MUST have exactly one index line, and every index line exactly
+one mini file: `lint` fails on drift. So:
+
+- **Add a mini** → add its one knowledge-free index line (descriptor + "load
+  when" hint), keep it under the word budget, then recompile.
+- **Remove a mini** → delete its file *and* its index line, then recompile.
+- **Rename a mini** → rename the file and update the index line's filename, then
+  recompile (the bundle's `<!-- module: … -->` marker tracks the new name).
+
+Keep edits within the "index is a menu, not a meal" rule: never migrate
+knowledge into the index to "clarify" it. If a mini's trigger is unclear, sharpen
+the "load when" condition, not by adding skill content.
+
+**Acceptance:** one index line per mini and one mini per index line; index still
+under ~200 words (~300 for >12 minis); no line reads like knowledge.
+
+## Editing content without regressing fidelity
+
+When the skill was produced by *conversion*, re-run the parity gate after
+substantive edits so you don't silently drop content:
+
+```bash
+python3 tools/hive.py parity skills/<category>/<domain> <source-dir>
+```
+
+Keep the ratio ≥ 85% (aim 95%+) with no unexplained dropped heading. When adding
+new original knowledge (no external source), there is nothing to parity against:
+just ensure the new mini is self-contained and the bundle recompiles clean.
+
+## Adding presets, especially for variant-split skills
+
+A **preset** is a named compiled subset of minis for a recurring configuration,
+built by the same concatenation rules as the bundle. Generate presets with the
+`--presets NAME=IDS` flag on `compile` (ids may be ordinals like `01`, stems, or
+filenames; comma-separated; order preserved):
+
+```bash
+python3 tools/hive.py compile skills/<category>/<domain> \
+  --presets security-audit=00-core,02 python-server=00-core,01,02,11,12
+```
+
+This writes `presets/security-audit.md` and `presets/python-server.md`. Presets
+SHOULD be few and named for real recurring tasks. Do not generate a
+combinatorial family speculatively.
+
+**The variant-split case is where presets earn their keep.** When a skill
+contains mutually-exclusive tracks, such as language variants (Python *vs* Node)
+or platform variants (iOS *vs* Android), a broad task should never load the whole
+bundle, because half of it is irrelevant to the chosen variant. Ship one preset
+per variant: each is `00-core` + the shared minis + only that variant's minis, so
+a "build the whole Python server" task loads `presets/python-server.md` in one
+read with zero cross-variant waste. Reference these presets in the INDEX's
+loading header or a note so the loader knows to prefer them for broad
+variant-specific work.
+
+**Acceptance:** each preset covers exactly one real recurring configuration;
+`presets/*.md` are tool-generated (never hand-edited); `lint` exits 0.
+
+## Conformance re-check
+
+Before considering maintenance done, confirm the skill still satisfies the spec:
+knowledge-free INDEX under budget with one "load when" line per mini; focused,
+self-contained, uncompressed minis each with an H1; a small `00-core` where
+warranted, marked always-load; a tool-generated, boundary-marked, never-
+hand-edited `BUNDLE.md` and any presets; passing parity (for converted skills);
+untouched non-knowledge assets. A single command reports lint status across every
+skill in the repo:
+
+```bash
+python3 tools/hive.py report skills
+```
+
+`report` prints a per-skill token/size table with a `lint (P/W/F)` column and
+exits nonzero if any skill has a lint FAIL. Use it as the final green light.
+
+**Acceptance:** `report skills` shows the maintained skill with `0F` (zero
+fails).

package/assets/skills/meta/ccs-skill-creator/composable/INDEX.md

@@ -0,0 +1,8 @@
+# CCS Skill Creator: Loading Menu
+
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If most of this skill is relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+
+- `mini/00-core.md` - what CCS is, the loading policy, the two iron rules, when NOT to use CCS - **always load**
+- `mini/01-create-new-skill.md` - author a new skill from scratch: scope, slice, write minis/core/index, compile, lint; worked example. Load when creating a new CCS skill with no source.
+- `mini/02-convert-existing-skill.md` - repackage any source (monolith, SKILL.md+references, prompt library): inventory, map, full-fidelity carry, parity-gate, lint. Load when converting an existing skill.
+- `mini/03-review-and-maintain.md` - editing minis and recompiling, keeping the index in sync, adding presets for variant-split skills, conformance re-check. Load when updating or maintaining a skill already in CCS format.

package/assets/skills/meta/ccs-skill-creator/composable/VERSION

@@ -0,0 +1 @@
+1.0.0