claude-dev-env 1.93.0 → 1.94.0

package/skills/session-tidy/SKILL.md

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 ## Overview
 
-Audit and consolidate session logs in the Obsidian vault (`sessions/[Project]/`) by enforcing the format contract, categorizing uncategorized files into project subfolders, resolving orphaned next-steps, updating stale statuses, and generating project rollup summaries.
+Audit and consolidate session logs in the Obsidian vault (`sessions/[Project]/`) by enforcing the tidy audit rules, categorizing uncategorized files into project subfolders, resolving orphaned next-steps, updating stale statuses, and generating project rollup summaries.
 
 **Announce at start:** "Running session log consolidation."
 
@@ -16,16 +16,23 @@ Audit and consolidate session logs in the Obsidian vault (`sessions/[Project]/`)
 
 ## The Format Contract
 
-Source: `journal:session-log` skill definition. Read that skill's SKILL.md if you need to verify the authoritative format.
+**Write-side HTML contract:** `/session-log` owns how new session reports are written — vault path, HTML frontmatter comment block, Artifact publish, and body design. Read `journal:session-log` SKILL.md for that contract. The markdown field shapes below describe files tidy may read; they are not the write path for new session reports.
 
-**Directory structure:** `sessions/[Project]/[N]. [Title].md`
-- Each project gets its own subfolder under `sessions/`
-- Session files are named `[N]. [Title].md` where Title is a 2-5 word summary of the primary outcome (e.g., `3. Amazon Auth Migration.md`)
-- Summary files are named `Summary.md` in the same project folder
+**What tidy audits:** Project folders under `sessions/` may hold `.html` session reports and `.md` session files. Audit every session file present. The rules in this skill are the single home for tidy audit criteria.
+
+**Directory structure:** `sessions/[Project]/`
+- Session files match `[N]. [Title].html` or `[N]. [Title].md`, where Title is a 2-5 word summary of the primary outcome (e.g., `3. Amazon Auth Migration.html`)
+- Summary files are `Summary.html` or `Summary.md` in the same project folder
 - No parenthetical suffixes like `(Wrap-Up)`
-- Files missing a title (e.g., `Session 1.md` or `1.md`) should be flagged for renaming -- read the content to derive a title
+- Files missing a title (e.g., `Session 1.md` or `1.html`) should be flagged for renaming — read the content to derive a title
+
+**Shared metadata fields (required on every session file):**
+`type`, `project`, `session`, `date`, `status`, `blocked`, `tags`
+
+**HTML session reports** — when tidy reads a `.html` session file, metadata sits in an HTML comment block at the start of the file content. The write-side comment shape lives in session-log SKILL.md. HTML reports also carry `session_id` and `vault_context_retrieved`.
+
+**Markdown session files** — when tidy reads a `.md` session file, metadata sits in YAML frontmatter:
 
-**Required frontmatter fields:**
 ```yaml
 ---
 type: session-report
@@ -38,40 +45,41 @@ tags: ["session", "[project-tag]"]
 ---
 ```
 
-**Content structure:**
+**Content structure for markdown session files:**
 - Section headers (`###`) use one emoji + outcome-oriented title
 - Valid emojis: ✅ (done), 🚫 (blocked), ⚠️ (note), 🔧 (in-progress), 📋 (queued)
 - Explanatory paragraphs under each header, not just bullets
 - Tables for 3+ rows of structured data
 - No play-by-play or process narration
 
+**Content structure for HTML session reports:** Body shape is session-specific (session-log designs per session). Tidy does not enforce a fixed HTML section template. Audit naming, metadata completeness, type, status coherence, orphaned next-steps text in the body, and categorization.
+
 ## The Process
 
 ### Phase 0: Preflight
 
-Determine which storage backend is available. Try in this order and use the first that succeeds:
+Determine which storage backend is available. First success wins:
 
-1. **Headless vault** -- run `ob --version` via Bash to verify the obsidian-headless CLI is installed. Then check `OBSIDIAN_VAULT_PATH` environment variable or `~/.claude/vault/` for a vault directory. If the CLI exists and a vault directory resolves, set `backend = "headless"`.
+1. **Headless vault** — same check as Backend Detection in `journal:session-log` SKILL.md: Bash `ob --version`, then `OBSIDIAN_VAULT_PATH` or `~/.claude/vault/`. When the CLI check succeeds and a vault directory resolves, set `backend = "headless"`.
 
-2. **Obsidian MCP** -- call `mcp__obsidian__list_directory` with `path="sessions"`. If it succeeds, set `backend = "obsidian"`.
+2. **Obsidian MCP** — call `mcp__obsidian__list_directory` with `path="sessions"`. If it succeeds, set `backend = "obsidian"`.
 
-3. **Local vault** -- use `~/.claude/vault/` as a local vault directory. Create it via `mkdir -p ~/.claude/vault/sessions` if it does not exist. Set `backend = "local"`.
+3. **Local vault** — same fallback as session-log Backend Detection: `~/.claude/vault/`. Create `~/.claude/vault/sessions` via `mkdir -p` if missing. Set `backend = "local"`.
 
-**Headless and local capability notes:** When running without Obsidian MCP, the following operations use alternative methods:
-- **Move/rename:** `mv` via Bash
-- **Frontmatter update:** Read + modify YAML + Write
-- **Search:** Bash `ls` + Grep
+**Capability notes by backend:**
+- **obsidian:** list, read, move, frontmatter update, and write via MCP tools (`list_directory`, `read_note`, `move_note`, `update_frontmatter`, `write_note`). For `.html` files, metadata edits use Read + Edit of the HTML comment block when MCP frontmatter tools do not apply.
+- **headless / local:** Move/rename via `mv` (Bash). Metadata update via Read + Edit/Write. Search via Bash `ls` + Grep.
 
 ### Phase 1: Audit
 
-List project subdirectories in `sessions/` via `mcp__obsidian__list_directory`. For each project folder, read its files via `mcp__obsidian__read_note`. Also check for any files sitting directly in `sessions/` (uncategorized). For each file, check:
+List project subdirectories in `sessions/` (MCP `list_directory` when backend is obsidian; Bash `ls` when headless or local). For each project folder, read its files. Also check for any files sitting directly in `sessions/` (uncategorized). Audit both `.html` and `.md` session files. For each file, check:
 
-1. **Naming convention?** Must match `[N]. [Title].md` where N is the session number and Title is a 2-5 word outcome summary. Flag bracket prefixes, date-only names, parenthetical suffixes, or legacy `Session [N].md` patterns missing a title.
-2. **Frontmatter complete?** All required fields present: `type`, `project`, `session`, `date`, `status`, `blocked`, `tags`.
+1. **Naming convention?** Must match `[N]. [Title].html` or `[N]. [Title].md` where N is the session number and Title is a 2-5 word outcome summary. Flag bracket prefixes, date-only names, parenthetical suffixes, or patterns missing a title such as `Session 1.md` or `1.html`.
+2. **Frontmatter complete?** All shared required fields present: `type`, `project`, `session`, `date`, `status`, `blocked`, `tags`. For `.html` session reports, also require `session_id` and `vault_context_retrieved`.
 3. **Type correct?** Must be `session-report`. Flag other types.
-4. **Status coherent?** `status: "completed"` with `blocked: true` is contradictory. `status: "in-progress"` or `status: "blocked"` on sessions older than 7 days is likely stale.
+4. **Status coherent?** `status: completed` with `blocked: true` is contradictory. `status: in-progress` or `status: blocked` on sessions older than 7 days is likely stale.
 5. **Orphaned next-steps?** Scan content for sections containing "Next", "Queued", "Session N+1", "TODO", or clipboard emoji sections. Cross-reference against subsequent sessions for the same project to determine if the items were addressed.
-6. **Categorized?** Files sitting directly in `sessions/` (not in a project subfolder) are uncategorized. Infer the project name from the filename pattern (e.g., `BudgetBridge Session 3.md` belongs in `sessions/BudgetBridge/`) or from the frontmatter `project` field. Flag for move into the correct subfolder.
+6. **Categorized?** Files sitting directly in `sessions/` (not in a project subfolder) are uncategorized. Infer the project name from the filename pattern (e.g., `BudgetBridge Session 3.md` belongs in `sessions/BudgetBridge/`) or from the frontmatter `project` field. Flag for a move into the correct subfolder.
 
 ### Phase 2: Propose Changes
 
@@ -83,8 +91,8 @@ Present a structured report:
   - **Resolved:** found evidence in a later session
   - **Orphaned:** no later session addresses it
   - **Unknown:** later sessions exist but don't clearly address or skip the item
-**Uncategorized files** -- files in `sessions/` root that should be moved into a project subfolder
-**Rollup candidates** -- projects with 3+ sessions that have no rollup/summary session
+**Uncategorized files** -- files in `sessions/` root that should live in a project subfolder
+**Rollup candidates** -- projects with 3+ sessions that have no `Summary.html` or `Summary.md`
 **Proposed actions** -- numbered list of specific changes
 
 Do NOT execute any changes yet. Wait for user approval.
@@ -93,14 +101,16 @@ Do NOT execute any changes yet. Wait for user approval.
 
 After user approves (all or selected items):
 
-1. **Rename** non-conforming files via `mcp__obsidian__move_note`.
-2. **Fix frontmatter** via `mcp__obsidian__update_frontmatter` -- set correct type, add missing fields.
+1. **Rename** non-conforming files via `mcp__obsidian__move_note` (obsidian) or `mv` (headless/local). Keep the file's extension (`.html` or `.md`).
+2. **Fix frontmatter:**
+   - `.md` files: `mcp__obsidian__update_frontmatter` when backend is obsidian; Read + Edit/Write of YAML frontmatter when headless or local. Set correct type; add missing shared fields.
+   - `.html` files: Read + Edit of the HTML comment block fields (shape in session-log SKILL.md). Set correct type; add missing shared fields plus `session_id` and `vault_context_retrieved` when absent.
 3. **Update stale statuses** -- change old in-progress/blocked to completed (or ask user for correct status).
 4. **Clean orphaned next-steps** -- for confirmed orphaned items, either:
    - Remove the section if all items are orphaned and the session is old
    - Add a strikethrough or "(not pursued)" annotation if some items remain relevant
    - Leave unchanged if user declines
-5. **Generate project rollups** -- for each qualifying project, write a summary note via `mcp__obsidian__write_note`:
+5. **Generate project rollups** -- for each qualifying project, write a summary note via `mcp__obsidian__write_note` (obsidian) or Write (headless/local):
    - **Path:** `sessions/[Project]/Summary.md`
    - **Frontmatter:** `{"type": "project-summary", "project": "[name]", "sessions": [count], "date_range": "[first] to [last]", "tags": ["summary", "[project-tag]"]}`
    - **Content:** Use this template:
@@ -123,14 +133,14 @@ After user approves (all or selected items):
 ### Carried Forward
 - [ ] [unresolved item from latest session]
 ```
-6. **Categorize uncategorized files** -- move files from `sessions/` root into the correct project subfolder via `mcp__obsidian__move_note`. When moving, rename to match the `[N]. [Title].md` convention (e.g., `sessions/BudgetBridge Session 3.md` becomes `sessions/BudgetBridge/3. [Title derived from content].md`).
+6. **Categorize uncategorized files** -- move files from `sessions/` root into the correct project subfolder via `mcp__obsidian__move_note` or `mv`. When moving, rename to match the `[N]. [Title].html` or `[N]. [Title].md` convention for that file's extension (e.g., `sessions/BudgetBridge Session 3.md` becomes `sessions/BudgetBridge/3. [Title derived from content].md`).
 
 ### Phase 4: Verify
 
 After execution, re-read the vault and confirm:
 - Every session file lives in a project subfolder under `sessions/[Project]/`
-- Every file has valid frontmatter with all required fields
-- Every filename matches the naming convention (`[N]. [Title].md` or `Summary.md`)
+- Every file has valid frontmatter with all required fields for its shape
+- Every filename matches the naming convention (`[N]. [Title].html`, `[N]. [Title].md`, `Summary.html`, or `Summary.md`)
 - No contradictory status/blocked combos
 - All orphaned next-steps resolved or annotated
 - Rollup summaries exist for qualifying projects

package/skills/skill-builder/CLAUDE.md

@@ -1,27 +1,29 @@
 # skill-builder
 
-Orchestrates the complete skill-building lifecycle: classify the skill type, scaffold folders, write via `skill-writer`, self-audit against a 38-point checklist, and refine from real usage observations.
+Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, self-audit, and refine from real usage.
 
-**Trigger:** "build a skill", "new skill workflow", "improve this skill", "optimize skill description", "skill development lifecycle".
+**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog.
 
 ## Purpose
 
-The expert that enforces craft standards. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context, delegates writing, and self-audits the result.
+Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (including composition plan and description triggers), delegates writing, and self-audits.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Hub — routing, 9-type taxonomy table, core principles, file index |
+| `SKILL.md` | Hub — routing, principles, file index |
 | `references/skill-types.md` | 9-type taxonomy with folder structures per type |
 | `references/progressive-disclosure.md` | Hub pattern, folder conventions, hard rules |
-| `references/self-audit-checklist.md` | 38-point mandatory post-build audit |
+| `references/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
+| `references/description-field.md` | Description as trigger catalog (not story prose) |
+| `references/self-audit-checklist.md` | Mandatory post-build audit |
 | `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
 | `references/thariq-x-post-skills.json` | Source reference — lessons from building Claude Code skills |
 | `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
 | `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
-| `workflows/polish-skill.md` | Description audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Template for documenting skill gaps |
+| `workflows/polish-skill.md` | Description trigger-catalog audit and final validation (5 steps) |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers |
 
 ## Subdirectories
 
@@ -40,6 +42,7 @@ The expert that enforces craft standards. For quick one-off SKILL.md edits, use
 
 ## Conventions
 
-- Every build ends with the 38-point self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
-- `skill-builder` orchestrates; `skill-writer` authors. The handoff packet must include type, gap analysis, degree-of-freedom assessment, and constraints.
-- The Claude A / Claude B pattern: Claude A (this session) designs; Claude B (subagents) tests by running the built skill on real tasks.
+- Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
+- Modularity items and description trigger-catalog items are mandatory on every delivery.
+- `skill-builder` orchestrates; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, degree-of-freedom assessment, and constraints.
+- Claude A / Claude B: Claude A (this session) designs; Claude B (subagents) tests the built skill on real tasks.

package/skills/skill-builder/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: skill-builder
 description: >-
-  Runs the skill-building lifecycle: type classification, scaffolding, writing
-  through skill-writer, self-audit against a checklist, and refinement from real
-  usage. Triggers: 'build a skill', 'new skill workflow', 'improve this skill',
-  'optimize skill description', 'skill development lifecycle'.
+  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose
+  sub-skills, polish description triggers. Triggers: build a skill, new skill
+  workflow, improve this skill, optimize skill description, skill development
+  lifecycle, skill modularity, skill composition, description trigger catalog.
 ---
 
 # Skill Builder
@@ -19,6 +19,10 @@ Highest-signal content. Append a bullet each time a skill build fails in a new w
 
 > "The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill."
 
+- Story-form `description` burns always-on context and weakens selection — rewrite to capability stem + `Triggers:` list (`description-field.md`).
+- Multi-capability packages fail modularity audit — split or thin orchestrator + named sub-skills (`skill-modularity.md`).
+- Skipping the composition plan before Write reintroduces silent reimplementation of peer skills.
+
 ## When this skill applies
 
 Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to `/skill-writer`, and self-audits the result.
@@ -60,23 +64,11 @@ The feedback loop: observe Claude B’s behavior, bring insights back, refine th
 
 > "After cataloging all of our skills, we noticed they cluster into a few recurring categories."
 
-Classify the skill into one of 9 types. The type determines folder structure. See `${CLAUDE_SKILL_DIR}/references/skill-types.md` for full details.
-
-| # | Type | Key folders |
-|---|---|---|
-| 1 | Library & API Reference | reference/, examples/ |
-| 2 | Product Verification | scripts/, reference/ |
-| 3 | Data Fetching & Analysis | reference/, scripts/ |
-| 4 | Business Process & Team Automation | templates/, scripts/ |
-| 5 | Code Scaffolding & Templates | templates/, scripts/ |
-| 6 | Code Quality & Review | reference/, scripts/ |
-| 7 | CI/CD & Deployment | workflows/, scripts/ |
-| 8 | Runbooks | reference/, templates/ |
-| 9 | Infrastructure Operations | reference/, scripts/ |
+Classify into one of 9 types — type sets folder structure. Taxonomy and layouts: [`references/skill-types.md`](references/skill-types.md).
 
 ## Principles
 
-These are non-negotiable. Every skill must satisfy them. The self-audit checklist enforces them.
+These are non-negotiable. Every skill must satisfy them. Enforce via [`references/self-audit-checklist.md`](references/self-audit-checklist.md).
 
 ### Concision and defaults
 
@@ -96,25 +88,27 @@ High freedom (text guidance) for open fields. Low freedom (exact scripts, no par
 
 ### Progressive disclosure
 
-> "Keep SKILL.md body under 500 lines."
+Hub pattern, line caps, one-level references, TOC and path rules: [`references/progressive-disclosure.md`](references/progressive-disclosure.md).
+
+### Modularity and composition
 
-SKILL.md is a hub. Detail lives in reference/, scripts execute without being read into context. References one level deep. Files over 100 lines get a TOC. Forward slashes only.
+One skill = one capability. Multi-step work invokes **sub-skills** (peer skills) by name. Prefer compose over reimplement. Full rules: [`references/skill-modularity.md`](references/skill-modularity.md).
 
-See `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md` for the full specification.
+> "You can just reference other skills by name, and the model will invoke them if they are installed."
 
-### Description field
+New-skill Gather records a composition plan before write. Self-audit modularity items are mandatory.
 
-> "Always write in third person. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
+### Description field (trigger catalog)
 
-Include what the skill does AND specific trigger phrases. Max 1024 chars.
+The frontmatter `description` is **selection metadata** pre-loaded for every skill. Write a **trigger catalog**, not a story: short capability stem + concrete trigger phrases. No narrative, benefits language, or process dump.
+
+Full rules: [`references/description-field.md`](references/description-field.md). Polish workflow Step 1 is the dedicated rewrite pass.
 
 > "The description field is not a summary — it’s a description of when to trigger."
 
 ### Gotchas
 
-> "Build a Gotchas Section — the highest-signal content in any skill."
-
-Mandatory section. Built from real failure observations. Updated over time as new failure modes surface.
+Mandatory highest-signal section (see Gotchas above). Capture real failure modes; self-audit requires the section present and actionable.
 
 ### Templates and examples
 
@@ -148,6 +142,8 @@ Multi-step processes get `[ ]` checklists. Quality-critical operations get feedb
 
 > No Windows paths. Don’t offer too many options — provide a default with escape hatch. Avoid time-sensitive claims. Use consistent terminology. No deeply nested references.
 
+Also: story-form descriptions; monolith multi-capability skills; silent reimplementation of peer skills; nested folders used as fake sub-skills.
+
 ## Self-audit
 
 After every build, improvement, or polish pass, run the mandatory checklist at `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`. Every item must pass before delivery. Fix failures, then re-audit.
@@ -157,9 +153,11 @@ After every build, improvement, or polish pass, run the mandatory checklist at `
 skill-builder orchestrates; skill-writer authors. The handoff packet from Step 4 must include:
 
 - Skill type and folder structure
-- Gap analysis or observation findings
+- Gap analysis or observation findings (composition plan + description triggers)
 - Degree of freedom assessment
 - Initial gotchas
+- Composition plan: related skills, sub-skills to invoke, split decisions
+- Description trigger catalog: capability stem + trigger phrases (not prose)
 - Any constraints
 
 See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
@@ -171,12 +169,14 @@ See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
 | `SKILL.md` | This hub — principles, process, routing, file index |
 | `references/skill-types.md` | 9-type taxonomy with folder structures per type |
 | `references/progressive-disclosure.md` | Folder conventions, hub pattern, hard rules |
-| `references/self-audit-checklist.md` | 38-point mandatory post-build audit |
+| `references/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
+| `references/description-field.md` | Description as trigger catalog (not story prose) |
+| `references/self-audit-checklist.md` | Mandatory post-build audit (core, modularity, description) |
 | `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
 | `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
 | `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
-| `workflows/polish-skill.md` | Description audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Template for documenting skill gaps |
+| `workflows/polish-skill.md` | Description trigger-catalog audit and final validation (5 steps) |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers |
 
 ## Folder map
 

package/skills/skill-builder/references/CLAUDE.md

@@ -6,14 +6,18 @@ Best-practice specifications and the mandatory self-audit checklist for the `/sk
 
 | File | Purpose |
 |---|---|
-| `self-audit-checklist.md` | 38-point checklist run after every build, improvement, or polish pass. Every item must pass before delivery. |
-| `skill-types.md` | 9-type skill taxonomy with folder structures per type (Library & API Reference, Product Verification, Data Fetching, Business Process, Code Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure). |
-| `progressive-disclosure.md` | Hub pattern, folder conventions, and hard rules: SKILL.md under 500 lines, detail in reference/, scripts execute without context load, references one level deep. |
-| `delegation-map.md` | Subagent handoff patterns and transcript guidance for the skill-builder → skill-writer handoff. |
+| `self-audit-checklist.md` | Checklist after every build, improvement, or polish pass. Every item must pass before delivery. |
+| `skill-types.md` | 9-type skill taxonomy with folder structures per type. |
+| `progressive-disclosure.md` | Hub pattern, folder conventions, hard rules: SKILL.md under 500 lines, one-level references. |
+| `skill-modularity.md` | Cross-skill modularity: one capability, sub-skills by name, composition plan, anti-monolith. |
+| `description-field.md` | Frontmatter description as trigger catalog (capability stem + Triggers). No story prose. |
+| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer. |
 | `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
 
 ## Conventions
 
-- These files are loaded on demand by `SKILL.md` routing — not all are loaded on every run.
-- `self-audit-checklist.md` is always loaded at the end of a build cycle.
+- These files load on demand from `SKILL.md` routing — not all on every run.
+- `self-audit-checklist.md` always loads at the end of a build cycle.
+- Load `skill-modularity.md` during Gather and when scope/overlap is diagnosed.
+- Load `description-field.md` during Gather, polish Step 1, and any activation diagnosis.
 - `thariq-x-post-skills.json` is source reference data, not executable content.

package/skills/skill-builder/references/delegation-map.md

@@ -13,17 +13,23 @@ Create a skill with these parameters:
 
 **Skill type:** [one of 9 types from skill-types.md]
 **Folder structure:** [directories to create: reference/, scripts/, etc.]
-**What it does:** [one-sentence capability description]
+**What it does:** [one-sentence capability — single job]
 **Domain context:** [what Claude needs to know that it doesn't already]
 **Initial gotchas:** [failure patterns to document from the start]
 **Degree of freedom:** [high | medium | low — with reasoning]
 **Constraints:** [non-negotiables]
+**Composition plan:** [related skills; sub-skills with when/produces/missing; leaf vs orchestrator]
+**Description (exact frontmatter string):** [capability stem. Triggers: phrase, phrase, ...]
+  — Trigger catalog only per description-field.md. No story prose.
 
 Produce:
 1. SKILL.md with hub layout (principle, gotchas, when-applies, process, file index, folder map)
-2. Companion files as needed (reference docs, workflow steps, templates)
-3. Every file under 500 lines; TOC on files over 100 lines
-4. File index listing every file and its purpose
+2. Frontmatter description set to the exact trigger-catalog string above
+3. Sub-skills table in body when composition plan lists peer skills
+4. Companion files as needed (reference docs, workflow steps, templates)
+5. Every file under 500 lines; TOC on files over 100 lines
+6. File index listing every file and its purpose
+7. No reimplementation of steps owned by named sub-skills
 ```
 
 ### Refine skill handoff
@@ -36,8 +42,11 @@ Refine this existing skill:
 **What to change:** [specific instructions to add/remove/modify]
 **New gotchas to add:** [failure patterns discovered]
 **What to preserve:** [working content — do not touch]
+**Description rewrite (if activation issue):** [exact new trigger-catalog string]
+**Composition change (if modularity issue):** [sub-skills to add/invoke or split plan]
 
 Constraint: Only change what the observations demand. Do not reorganize working content.
+Description must remain a trigger catalog (description-field.md), never story prose.
 ```
 
 ## Spawning a test subagent

package/skills/skill-builder/references/description-field.md

@@ -0,0 +1,113 @@
+# Description field (trigger catalog)
+
+Source: [Anthropic — Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) (Writing effective descriptions; metadata pre-load), [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills), Thariq lessons (`thariq-x-post-skills.json`).
+
+## Role
+
+At session start, **only** each skill’s `name` and `description` load into context. The body loads after selection.
+
+The description is **selection metadata**, not a summary of the skill and not process documentation. It answers: *should Claude load this skill for this user turn?*
+
+> "The description field is not a summary — it’s a description of when to trigger."
+
+> "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
+
+## Hard limits
+
+| Rule | Value |
+|---|---|
+| Voice | Third person only (no I/you) |
+| Max length | 1024 characters |
+| XML | Forbidden |
+| Empty | Forbidden |
+
+## Required shape: trigger catalog
+
+Two parts, dense, no story prose:
+
+1. **Capability stem** (what) — 5–20 words of capability tokens. Fragments or semicolon-separated verbs. No motivation, no audience address, no “helps you”.
+2. **Triggers** (when) — concrete phrases, slash-commands, file types, and domain nouns the user or model might emit. Prefer a labeled `Triggers:` segment.
+
+### Canonical template
+
+```yaml
+description: >-
+  <capability tokens>. Triggers: <phrase>, <phrase>, <slash>, <filetype>, <near-miss exclusion if needed>.
+```
+
+### Good
+
+```yaml
+description: >-
+  Extract PDF text/tables; fill forms; merge docs. Triggers: PDF, .pdf, forms, document extraction, fill this form, merge PDFs.
+```
+
+```yaml
+description: >-
+  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
+```
+
+```yaml
+description: >-
+  Generate commit messages from git diffs. Triggers: commit message, write a commit, staged changes, git commit help.
+```
+
+### Bad (story / waste)
+
+```yaml
+# Narrative — burns always-on tokens, weak for matching
+description: >-
+  This skill helps you work with PDF files by guiding Claude through a careful
+  process of extraction and form filling so you get reliable results every time.
+```
+
+```yaml
+# Vague — no match surface
+description: Helps with documents
+```
+
+```yaml
+# Implementation dump — body material, not metadata
+description: >-
+  Uses pdfplumber and a five-step validate loop. See scripts/ for helpers.
+```
+
+```yaml
+# First/second person
+description: I can help you process Excel files
+description: You can use this to process Excel files
+```
+
+## Authoring steps
+
+1. List **capability tokens** (what the skill owns in one breath).
+2. List **10+ user phrasings** that should select this skill (formal, casual, slash, file-type).
+3. List **near-misses** that must *not* select it (sibling skills). Fold only the shortest distinguishing tokens into Triggers if needed.
+4. Assemble stem + `Triggers:` list. Strip adjectives, benefits, and process narrative.
+5. Count characters (≤1024). Prefer under ~400 when possible — every skill’s description is always loaded.
+6. Run the checklist below.
+
+## Description checklist
+
+```
+- [ ] Third person; no I/you
+- [ ] Capability stem present (what), ≤20 words of tokens
+- [ ] Triggers: segment (or equivalent dense when-list) with concrete phrases
+- [ ] No story prose, benefits language, or implementation steps
+- [ ] No XML; length ≤1024
+- [ ] Distinguishable from sibling skills in the same domain
+- [ ] Body holds process detail — not the description
+```
+
+## Where process lives
+
+| Content | Location |
+|---|---|
+| When to select the skill | `description` frontmatter |
+| How to run the skill | SKILL.md body + companions |
+| Refusal / boundary narrative | When-this-applies section in body |
+| Sub-skill invocation | Body Sub-skills table (`skill-modularity.md`) |
+
+## Polish workflow
+
+`workflows/polish-skill.md` Step 1 is the dedicated description pass: rewrite any story description into a trigger catalog and re-check discovery against phrase lists.

package/skills/skill-builder/references/self-audit-checklist.md

@@ -12,8 +12,12 @@ Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en
   > "Match the level of specificity to the task's fragility and variability."
 - [ ] **Naming convention** — Name uses gerund form (verb-ing) unless it's a well-known acronym or proper name. Lowercase, numbers, hyphens only. Max 64 chars. No reserved words.
   > "Use consistent naming patterns to make Skills easier to reference."
-- [ ] **Description field** — Third person. Includes what AND when. Specific trigger phrases. Max 1024 chars. No XML tags.
+- [ ] **Description is a trigger catalog** — Capability stem (what tokens) + concrete Triggers list (when). Third person. Max 1024 chars. No XML. Spec: `description-field.md`.
   > "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
+- [ ] **Description is not a story** — No narrative prose, benefits language ("helps you"), first/second person, or process/implementation dump in frontmatter.
+  > "The description field is not a summary — it's a description of when to trigger."
+- [ ] **Description match surface** — Includes specific phrases, slash forms, and file types a user would say; distinguishable from sibling skills.
+  > "Be specific and include key terms."
 - [ ] **SKILL.md body under 500 lines**
   > "Keep SKILL.md body under 500 lines for optimal performance."
 - [ ] **One level deep** — All reference files link directly from SKILL.md. No nested references.
@@ -78,10 +82,23 @@ Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en
 - [ ] **Persistent data uses `${CLAUDE_PLUGIN_DATA}`** — Not stored in skill directory itself.
   > "Data stored in the skill directory may be deleted when you upgrade the skill."
 
-## Composition and measurement (if applicable)
+## Modularity and composition
 
-- [ ] **Skill dependencies documented** — Skills this one composes with are named.
+Mandatory for every skill. Spec: `skill-modularity.md`. Progressive disclosure (file split) does not satisfy these items.
+
+- [ ] **Single capability boundary** — One clear job in one sentence. Unrelated jobs are separate skills or an orchestrator that only routes to named sub-skills.
+  > "The best skills fit cleanly into one; the more confusing ones straddle several."
+- [ ] **Compose before reimplement** — Steps an existing skill already owns are invoked by name, not pasted into this package. Local reimplementation has a one-line why in the gap analysis or gotchas.
   > "You can just reference other skills by name, and the model will invoke them if they are installed."
+- [ ] **Sub-skills table (when composing)** — Each invoked skill lists when to call it, what it produces, and missing-install behavior. N/A only when the skill is a pure leaf (invokes no peers).
+  > "You may want to have skills that depend on each other."
+- [ ] **Sibling boundary clear** — Description and when-this-applies distinguish this skill from related skills in the same domain. No silent overlap.
+  > "The description field is not a summary — it's a description of when to trigger."
+- [ ] **No monolith packing** — Multi-capability content is not stuffed under one description. Either split packages or thin orchestrator + peer sub-skills (not nested fake skills under `workflows/`).
+  > skill-modularity.md — anti-patterns: monolith, silent reimplementation, folder nesting as composition.
+
+## Hooks (if applicable)
+
 - [ ] **Hooks declared** — If skill registers hooks, their purpose and scope is stated.
   > "Skills can include hooks that are only activated when the skill is called."
 
@@ -89,4 +106,4 @@ Source synthesis: [Anthropic best practices](https://platform.claude.com/docs/en
 
 ## Usage
 
-Copy this checklist into your response after building. Check off each item. Any item that fails → fix before delivering. Any item marked "if applicable" that doesn't apply → mark N/A with a one-line reason.
+Copy this checklist into your response after building. Check off each item. Any item that fails → fix before delivering. Any item marked "if applicable" that doesn't apply → mark N/A with a one-line reason. Sub-skills table may be N/A for pure leaf skills; single capability boundary and no-monolith never are.