claude-dev-env 1.93.1 → 1.94.0

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

@@ -0,0 +1,113 @@
+# Skill modularity and composition
+
+Source: [Lessons from Building Claude Code](thariq-x-post-skills.json) — Composing Skills; skill type notes on skill dependencies; Anthropic progressive disclosure (within-skill layering).
+
+## Two modularity layers
+
+| Layer | What it controls | Where enforced |
+|---|---|---|
+| **Within skill** | SKILL.md stays a hub; detail lives in companion files | `progressive-disclosure.md`, self-audit line-cap items |
+| **Across skills** | One skill = one capability; multi-step work invokes sibling skills by name | This file, self-audit modularity items, new/improve workflows |
+
+Both layers apply. Progressive disclosure alone does not make a multi-capability skill modular.
+
+## Core rules
+
+### One capability per skill
+
+A skill owns **one** clear job a user can name in one sentence. Signals it is too large:
+
+- Description needs "and" for unrelated jobs
+- Process has independent branches that never share gotchas or scripts
+- Claude B only ever needs half the package for a typical task
+- Gotchas cluster into two or more unrelated failure domains
+
+When those hold, split or restructure as an orchestrator + sub-skills (below).
+
+### Compose by name (sub-skills)
+
+> "You can just reference other skills by name, and the model will invoke them if they are installed."
+
+There is no native dependency installer. Composition works by:
+
+1. Naming the sibling skill (`/skill-name` or the skill's trigger description).
+2. Stating **when** to invoke it (which process step).
+3. Stating **what** it must produce for the next step.
+4. Stating what to do if it is missing (refuse, degrade, or ask the user).
+
+**Sub-skill** means a focused skill another skill invokes — not a nested folder inside the parent package. Sub-skills are peer skills in the skill library.
+
+### Prefer invoke over reimplement
+
+When an existing skill already owns a step (PR scope resolve, self-audit handoff pattern, commit protocol, etc.), the new skill **names and invokes** that skill. It does not paste a second copy of that process into its own SKILL.md.
+
+Exception: the existing skill is wrong for this domain, and the gap analysis records why a local procedure is required.
+
+### Orchestrator skills
+
+Some capabilities are multi-step by nature (lifecycle skills, PR loops). The modular shape is:
+
+```
+orchestrator-skill/          # thin: routing, order, refusal, handoff packets
+  SKILL.md                   # invokes named sub-skills at each step
+sibling-skill-a/             # one capability
+sibling-skill-b/             # one capability
+```
+
+The orchestrator owns sequence and gates. Sub-skills own domain detail. skill-builder itself follows this shape: it orchestrates and delegates writing to `/skill-writer`.
+
+### Within-skill vs split
+
+| Situation | Choice |
+|---|---|
+| One capability, large reference surface | Stay one skill; use progressive disclosure |
+| Two capabilities that users invoke separately | Two skills |
+| Multi-step workflow that always runs end-to-end | Orchestrator skill + named sub-skills for reusable steps |
+| Overlap with an existing skill | Shrink the new skill; invoke the existing one; tighten both descriptions |
+
+## Composition plan (required before write)
+
+Every new skill and every improve pass that changes scope records a composition plan in the gap analysis:
+
+1. **Capability sentence** — one job.
+2. **Related skills inventory** — existing skills that touch the same domain (scan installed skills and the package tree).
+3. **Reuse** — which steps invoke which skills.
+4. **Split** — if more than one capability, list the skills to create or keep separate.
+5. **Missing** — sub-skills that do not exist yet (build them first or as sibling packages in the same change).
+
+## How to document sub-skills in SKILL.md
+
+In Process or a dedicated **Sub-skills** section:
+
+```markdown
+## Sub-skills
+
+| Skill | When | Produces |
+|---|---|---|
+| `/pr-scope-resolve` | Step 1 — resolve the PR target | owner, repo, PR number, head ref |
+| `/skill-writer` | Step 4 — author SKILL.md | skill package files |
+
+If a listed skill is not installed, respond: `[exact refusal or degrade line]`.
+```
+
+Self-audit requires this table (or equivalent) whenever the skill composes others.
+
+## Anti-patterns
+
+- **Monolith skill** — one package that reimplements commit, review, deploy, and logging under one description.
+- **Silent reimplementation** — copy-pasted steps from another skill with no name reference.
+- **Folder nesting as composition** — burying a second skill's content under `workflows/` instead of a real sibling skill the model can select.
+- **Vague dependency** — "use other skills as needed" with no names, when, or outputs.
+- **Redundant twin** — a new skill whose description overlaps an existing one without a refusal boundary.
+
+## Checklist for authors
+
+Copy into the response during new-skill Gather and improve Diagnose:
+
+```
+- [ ] Capability fits one sentence without an unrelated "and"
+- [ ] Related skills scanned; inventory written
+- [ ] Reusable steps map to named skills (or justify local procedure)
+- [ ] Multi-capability work is split or is an orchestrator with sub-skills
+- [ ] SKILL.md will name each sub-skill with when + produces + missing behavior
+```

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

@@ -149,6 +149,8 @@ Skills that help fetch, push, and deploy code.
 
 > "These skills may reference other skills to collect data."
 
+Compose peer skills by name (see `skill-modularity.md`). Do not paste those peers' procedures into this package.
+
 **Examples:** `babysit-pr`, `deploy-<service>`, `cherry-pick-prod`
 
 **Folder structure:**
@@ -226,3 +228,5 @@ skill-name/
 | "Manage infrastructure / cleanup" | 9. Infrastructure Operations |
 
 When the skill straddles multiple types, pick the dominant one for folder structure and note the secondary influence.
+
+If it straddles **capabilities** (not just types), split into separate skills or a thin orchestrator plus sub-skills — see `skill-modularity.md`. Frontmatter `description` stays a trigger catalog for whichever package owns the job — see `description-field.md`.

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

@@ -1,14 +1,14 @@
 # skill-builder/templates
 
-Reusable template for skill-building artifacts.
+Reusable templates for skill-building artifacts.
 
 ## Key files
 
 | File | Purpose |
 |---|---|
-| `gap-analysis.md` | Template for documenting gaps in an existing skill. Used during the "improve existing skill" workflow (Step 2 observation gathering) to structure findings before writing a new version. |
+| `gap-analysis.md` | Template for gaps, composition plan, and description triggers. Used in new-skill Gather and improve diagnosis. |
 
 ## Conventions
 
-- The gap-analysis template is loaded by the `improve-skill.md` workflow, not the `new-skill.md` workflow.
-- Fill in the template inline during the workflow; do not commit completed gap analyses to this directory.
+- Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
+- Composition plan and Description triggers sections are required before Write on a new skill.

package/skills/skill-builder/templates/gap-analysis.md

@@ -6,12 +6,36 @@
 
 ## Task Description
 
-[What the user is trying to accomplish — the capability this skill should provide]
+[One capability sentence — the single job this skill owns]
 
 ## Degree of Freedom
 
 [High | Medium | Low] — [Reasoning based on task fragility and variability]
 
+## Composition Plan
+
+See `references/skill-modularity.md`.
+
+- **Capability sentence:** [one job, no unrelated "and"]
+- **Related skills inventory:** [skill → keep separate | invoke as sub-skill | absorb + reason]
+- **Sub-skills to invoke:** [name → when → produces → missing behavior]
+- **Split or orchestrator:** [one leaf skill | several skills | thin orchestrator + peers]
+- **Missing sub-skills to create:** [names to build first or as siblings]
+
+## Description Triggers
+
+See `references/description-field.md`. Not story prose.
+
+- **Capability stem tokens:** [5–20 words]
+- **Trigger phrases:** [comma-separated phrases, slash forms, file types]
+- **Near-miss exclusions:** [tokens that must not select this skill]
+- **Draft description string:**
+
+```yaml
+description: >-
+  <stem>. Triggers: <phrases>.
+```
+
 ## Gaps Identified
 
 ### Gap 1: [Descriptive Name]

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

@@ -6,12 +6,14 @@ Step-by-step workflow files for each skill lifecycle phase, loaded on demand by
 
 | File | Purpose |
 |---|---|
-| `new-skill.md` | Full lifecycle for creating a new skill: 6 steps from intent capture through type classification, folder scaffolding, writing via skill-writer, self-audit, and delivery. |
-| `improve-skill.md` | Observation-first flow for improving an existing skill: 6 steps starting from real usage failures, gap analysis, targeted rewrite, and re-audit. |
-| `polish-skill.md` | Description audit and final validation: 5 steps for description optimization, trigger phrase review, and checklist sign-off. |
+| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers), write via skill-writer, self-audit, deliver. |
+| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality, targeted fix, re-audit. |
+| `polish-skill.md` | Description trigger-catalog audit, progressive disclosure + modularity audit, checklist sign-off. |
 
 ## Conventions
 
 - `SKILL.md` routes to exactly one workflow file per invocation based on the user's intent (new / improve / polish).
-- Each workflow references `../references/self-audit-checklist.md` at its final step.
+- Each workflow references `../references/self-audit-checklist.md` at its final verification step.
+- New and improve load `skill-modularity.md` and `description-field.md` when gathering or diagnosing.
+- Polish Step 1 is the dedicated description rewrite pass.
 - Load only the workflow that matches the active task; the other two stay out of context.

package/skills/skill-builder/workflows/improve-skill.md

@@ -28,15 +28,7 @@ Spawn a subagent with the existing skill on a real task (see delegation-map.md f
 
 ### Transcript analysis
 
-> "Watch for unexpected exploration paths, missed connections, overreliance on certain sections, and ignored content."
-
-Document:
-- Where did the skill work well?
-- Where did it fail or produce subpar results?
-- Did Claude B follow the skill’s instructions as written?
-- Did Claude B ignore any sections or files?
-- Did Claude B explore in unexpected directions?
-- What would a gotcha have prevented?
+Follow **Reading a transcript for observations** in `${CLAUDE_SKILL_DIR}/references/delegation-map.md`. Note what worked, what failed, and which gotcha would have prevented each failure.
 
 **Output:** Observation notes with specific failure examples.
 
@@ -50,8 +42,11 @@ Failure classification:
 
 | Symptom | Diagnosis | Apply |
 |---|---|---|
-| Skill never activates when it should | Description missing trigger phrases or too vague | Principles: Description field |
-| Skill activates when it shouldn’t | Description too broad, no refusal cases | Principles: Constraints and refusal cases |
+| Skill never activates when it should | Description missing trigger phrases, story prose, or too vague | `description-field.md` trigger catalog |
+| Skill activates when it shouldn’t | Description too broad / story; no refusal boundary | Description triggers + Constraints / when-this-applies |
+| Description is multi-sentence narrative | Description used as summary/story | Rewrite per `description-field.md` |
+| Skill owns unrelated jobs | Monolith / multi-capability | `skill-modularity.md` — split or orchestrator + sub-skills |
+| Skill reimplements another skill’s steps | Silent reimplementation | Compose by name; sub-skills table |
 | Claude reads wrong files first | Structure not intuitive, hub doesn’t guide well | Progressive disclosure |
 | Claude ignores a companion file | File not signaled in SKILL.md or poorly linked | File index, hub pattern |
 | Claude over-explains basics | Skill states what Claude already knows | Principles: Concision |
@@ -60,6 +55,8 @@ Failure classification:
 | Claude errors on script execution | Script doesn’t handle errors, missing deps | Principles: Scripts |
 | Output format is wrong | Missing template or examples | Principles: Templates and examples |
 
+When scope or activation is in play, re-read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md` and `${CLAUDE_SKILL_DIR}/references/description-field.md`.
+
 **Output:** Diagnosis per failure — which best practice was violated.
 
 ---
@@ -72,9 +69,11 @@ Failure classification:
 
 For each diagnosis from Step 2:
 
-1. Read the relevant section in `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md` or the SKILL.md principles.
+1. Read the matching reference (`description-field.md`, `skill-modularity.md`, `progressive-disclosure.md`, or SKILL.md principles).
 2. Make the minimum change that addresses the failure.
-3. Verify the fix doesn’t break anything that was working.
+3. For description failures: rewrite frontmatter into a trigger catalog (capability stem + Triggers list); strip story prose.
+4. For modularity failures: add sub-skills table, split packages, or thin the orchestrator; do not paste peer skill procedures.
+5. Verify the fix doesn’t break anything that was working.
 
 Delegate larger rewrites to `/skill-writer` using the refine-skill handoff from delegation-map.md.
 
@@ -121,6 +120,8 @@ Present to the user:
 1. **What was observed** — summary of failures from Step 1.
 2. **What was diagnosed** — which best practices were violated.
 3. **What changed** — delta summary (files modified, lines added/removed).
-4. **New gotchas added** — list of gotchas captured.
-5. **Audit summary** — post-fix audit results.
-6. **Suggested re-test** — a concrete task to verify the fix with Claude B.
+4. **Description** — final frontmatter if rewritten (paste the trigger catalog).
+5. **Composition** — sub-skills or splits if modularity changed.
+6. **New gotchas added** — list of gotchas captured.
+7. **Audit summary** — post-fix audit results.
+8. **Suggested re-test** — a concrete task to verify the fix with Claude B.

package/skills/skill-builder/workflows/new-skill.md

@@ -52,10 +52,12 @@ Best-practice-driven lifecycle for building a skill from scratch.
 
 ## Step 3: Gather
 
-**Goal:** Collect domain knowledge, failure patterns, and gotchas from the user.
+**Goal:** Collect domain knowledge, failure patterns, gotchas, and a composition plan.
 
 > "Build a Gotchas Section — these sections should be built up from common failure points that Claude runs into when using your skill."
 
+Read `${CLAUDE_SKILL_DIR}/references/skill-modularity.md` and `${CLAUDE_SKILL_DIR}/references/description-field.md` before the interview. Modularity and description triggers are gates: do not proceed to Write until the composition plan and trigger catalog drafts are filled.
+
 ### Interview questions
 
 Ask the user:
@@ -68,16 +70,26 @@ Ask the user:
 6. "Are there rules or constraints Claude must never violate?"
 7. "What tools, scripts, or libraries does Claude need to use?"
 8. "Does this skill need to run differently for different models (Haiku vs Opus)?"
+9. "In one sentence, what is the single capability this skill owns?"
+10. "Which existing skills already cover a step of this work? Which steps should this skill invoke by name?"
+11. "Is this one skill, several skills, or a thin orchestrator that calls sub-skills?"
+12. "What exact phrases, slash commands, or file types should select this skill?"
+
+### Related-skills inventory
+
+Scan installed skills and the package skill tree for names that touch the same domain. List each with: keep separate / invoke as sub-skill / absorb (with reason if absorb).
 
 ### Generate gap analysis
 
 Use the template at `${CLAUDE_SKILL_DIR}/templates/gap-analysis.md`. Fill in:
 
 - Skill type and degree of freedom
-- Task description
+- Task description (one capability sentence)
 - Gaps identified (what failed, what was needed)
 - Recurring patterns across gaps
 - Initial gotcha candidates
+- **Composition plan** — capability sentence, related skills, sub-skills to invoke, split or orchestrator decision, missing sub-skills to create
+- **Description triggers** — capability stem tokens + trigger phrase list (not story prose)
 
 ### Assess degree of freedom
 
@@ -91,7 +103,15 @@ Use the template at `${CLAUDE_SKILL_DIR}/templates/gap-analysis.md`. Fill in:
 
 Record the assessment with reasoning.
 
-**Output:** Completed gap analysis, initial gotchas list, degree-of-freedom assessment.
+### Modularity gate
+
+Copy the author checklist from `skill-modularity.md` and check every box. If the capability sentence needs an unrelated "and", stop and split scope with the user before Step 4.
+
+### Description gate
+
+Draft the frontmatter description using the template in `description-field.md`. Copy the description checklist and check every box. Story prose fails the gate.
+
+**Output:** Completed gap analysis (composition plan + description triggers), initial gotchas, degree-of-freedom assessment, modularity checklist, draft description.
 
 ---
 
@@ -101,7 +121,7 @@ Record the assessment with reasoning.
 
 Delegate to `/skill-writer` using the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
 
-The handoff must include: skill type, folder structure, gap analysis, initial gotchas, degree of freedom, constraints.
+The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter.
 
 After skill-writer produces the draft:
 
@@ -109,8 +129,10 @@ After skill-writer produces the draft:
 2. Verify SKILL.md body is under 500 lines.
 3. Verify all references are one level deep.
 4. Verify files over 100 lines have a TOC.
+5. Verify modularity: single capability, sub-skills table when composing, no silent reimplementation of inventoried skills.
+6. Verify description is a trigger catalog per `description-field.md` (not story prose).
 
-Fix structural issues before proceeding.
+Fix structural, modularity, and description issues before proceeding.
 
 **Output:** Complete skill package at the target directory.
 
@@ -134,14 +156,16 @@ For an independent check, spawn a subagent to run the audit (see delegation-map.
 
 ## Step 6: Deliver
 
-**Goal:** Hand off the finished skill with full documentation.
+**Goal:** Hand off the finished skill with full documentation. Prompt user if they want a PR up with the skill.
 
 Present to the user:
 
 1. **File map** — every file created, with its purpose.
 2. **Skill type** — classification and why it fits.
 3. **Degree of freedom** — assessment and reasoning.
-4. **Gotchas seeded** — initial gotchas captured.
-5. **Audit summary** — "All 38 items: N passed, M N/A."
-6. **Maintenance notes** — what to watch for in future usage that might warrant iteration.
-7. **Suggested first test** — a concrete task to try with Claude B.
+4. **Composition plan** — capability sentence, sub-skills invoked, any skills split out.
+5. **Description** — final frontmatter trigger catalog (paste the string).
+6. **Gotchas seeded** — initial gotchas captured.
+7. **Audit summary** — "All checklist items: N passed, M N/A."
+8. **Maintenance notes** — what to watch for in future usage that might warrant iteration.
+9. **Suggested first test** — a concrete task to try with Claude B.

package/skills/skill-builder/workflows/polish-skill.md

@@ -10,70 +10,83 @@ Final optimization pass for a skill that is functionally complete.
 
 ---
 
-## Step 1: Description Audit
+## Step 1: Description trigger-catalog audit
 
-**Goal:** Verify the description field is optimized for model discovery.
+**Goal:** Rewrite the frontmatter `description` into a dense trigger catalog. Selection metadata only — not a story.
+
+Read `${CLAUDE_SKILL_DIR}/references/description-field.md` and apply its checklist in full.
 
 > "The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills."
 
 > "The description field is not a summary — it's a description of when to trigger."
 
-Check each requirement:
+### Fail conditions (must rewrite)
+
+- Multi-sentence narrative or benefits language ("helps you", "ensures reliable…")
+- First or second person
+- Process/implementation detail that belongs in the body
+- Missing concrete trigger phrases
+- Overlap with a sibling skill with no distinguishing tokens
+
+### Required shape
+
+```yaml
+description: >-
+  <capability tokens>. Triggers: <phrase>, <phrase>, <slash>, <filetype>.
+```
 
-- [ ] **Third person.** "Processes Excel files" not "I can help you process Excel files."
-- [ ] **Includes what AND when.** Both the capability and trigger contexts.
-- [ ] **Specific trigger phrases.** Different phrasings of the same intent should all match.
-- [ ] **Under 1024 characters.** Hard limit.
-- [ ] **No XML tags.**
-- [ ] **Distinguishable from similar skills.** If two skills overlap, the descriptions must make the boundary clear.
+### Checklist
+
+- [ ] **Third person** — no I/you
+- [ ] **Capability stem** — what tokens, ≤20 words, no story
+- [ ] **Triggers list** — concrete phrases / slash forms / file types
+- [ ] **Under 1024 characters** (prefer much shorter; always-on context)
+- [ ] **No XML tags**
+- [ ] **Not a story** — no narrative, benefits, or process dump
+- [ ] **Sibling boundary** — distinguishable from related skills
 
 ### Trigger phrase review
 
 Generate 10 variations of the user's intent:
+
 - Formal and casual phrasings
-- Cases where the user doesn't explicitly name the skill but clearly needs it
+- Cases where the user doesn't name the skill but clearly needs it
 - Cases where this skill competes with another but should win
 
-For each, answer: would the current description cause Claude to select this skill?
+For each: would the current description select this skill?
+If you aren't sure of user's intent, present options to the user via askuserquestion for trigger phases.
 
-Also check 5 near-miss phrasings — adjacent domains where this skill should NOT trigger. Verify the description doesn't cause false activation.
+Also check 5 near-miss phrasings — adjacent domains that must not activate. Adjust Triggers tokens only as needed for boundary.
 
-### Fix issues
+### Fix
 
-If the description fails any check, revise it. Show before/after with the specific change and why it improves discovery.
+If any check fails, rewrite. Show before/after. The after form must match `description-field.md` good examples.
 
-**Output:** Verified description (and revised version if changes were made).
+**Output:** Final description string (trigger catalog).
 
 ---
 
-## Step 2: Progressive Disclosure Audit
-
-**Goal:** Verify the file structure follows all progressive disclosure rules.
-
-> "Keep SKILL.md body under 500 lines."
+## Step 2: Progressive disclosure and modularity audit
 
-Check:
+**Goal:** Verify within-skill structure and cross-skill modularity.
 
-- [ ] SKILL.md body under 500 lines.
-- [ ] All reference files link directly from SKILL.md (one level deep).
-- [ ] Every file over 100 lines has a table of contents.
-- [ ] File index in SKILL.md lists every companion file with its purpose.
-- [ ] Forward slashes only in all paths.
-- [ ] File names are descriptive (`form_validation_rules.md`, not `doc2.md`).
-- [ ] Scripts clearly marked as execute vs read-as-reference.
+1. Apply hard rules in `${CLAUDE_SKILL_DIR}/references/progressive-disclosure.md`.
+2. Apply modularity rules in `${CLAUDE_SKILL_DIR}/references/skill-modularity.md`.
+3. Cross-check matching items on `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
 
-### Fix structural issues
+### Common fixes
 
-If any check fails, restructure. Common fixes:
-- SKILL.md too long → move sections to companion files, leave links.
-- Nested references → surface all links to SKILL.md.
-- Missing TOC → add to files over 100 lines.
+- SKILL.md too long → move sections to companion files, leave links
+- Nested references → surface all links on SKILL.md
+- Missing TOC → add to files over 100 lines
+- Multi-capability package → split or orchestrator + named sub-skills
+- Silent reimplementation → invoke peer skill by name; add Sub-skills table
 
-**Output:** Verified file structure (and restructured files if changes were made).
+**Output:** Verified structure and composition (and edits if needed).
 
 ---
 
-## Step 3: Gotcha Freshness
+## Step 3: Gotcha freshness
 
 **Goal:** Ensure gotchas reflect current observations.
 
@@ -83,20 +96,22 @@ If any check fails, restructure. Common fixes:
 - Check against recent usage: are there new failure modes not yet captured?
 - Remove gotchas for issues that no longer occur (the skill fixed them).
 - Verify each gotcha is actionable — a reader should know what to avoid and why.
+- Verify they are relevant by going over them 1 by 1 with the user via AskUserQuestion.
 
 **Output:** Updated gotchas section (and any new gotchas for skill-builder itself).
 
 ---
 
-## Step 4: Full Self-Audit
+## Step 4: Full self-audit
 
-**Goal:** Complete 38-point checklist pass.
+**Goal:** Complete checklist pass including description and modularity items.
 
 Same as new-skill Step 5 and improve-skill Step 5:
 
 1. Read `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`.
 2. Check every item. Fix failures. Re-check.
 3. All items must be PASS or N/A.
+4. Description items and modularity items are never N/A for a delivered skill (sub-skills table alone may be N/A for pure leaf skills).
 
 **Output:** Completed checklist.
 
@@ -108,9 +123,10 @@ Same as new-skill Step 5 and improve-skill Step 5:
 
 Present to the user:
 
-1. **Description** — final version, confirmed trigger phrases.
-2. **File structure** — folder map with line counts.
-3. **Gotchas** — current gotcha count and most recent additions.
-4. **Audit summary** — "All 38 items: N passed, M N/A."
-5. **Before/after** — description changes if any, structural changes if any.
-6. **Maintenance notes** — what to watch for, when to re-audit.
+1. **Description** — final trigger-catalog string (paste it).
+2. **Composition** — sub-skills or leaf status.
+3. **File structure** — folder map with line counts.
+4. **Gotchas** — current gotcha count and most recent additions.
+5. **Audit summary** — "All checklist items: N passed, M N/A."
+6. **Before/after** — description rewrite and structural changes if any.
+7. **Maintenance notes** — what to watch for, when to re-audit.

package/skills/usage-pause/SKILL.md

@@ -1,10 +1,6 @@
 ---
 name: usage-pause
-description: >-
-  Waits out the account's 5-hour usage window in ScheduleWakeup stages that keep
-  every agent context warm. Accepts a manual override like '/usage-pause
-  10:20pm' or '/usage-pause 74m'. Triggers: '/usage-pause', 'pause until the
-  usage window resets', 'wait out the usage limit', 'usage limit pause'.
+description: 5-hour usage window, agent context warm, weekly limit is near its cap. Triggers: '/usage-pause', 'pause until the usage window resets', 'wait out the usage limit', 'usage limit pause', 'usage limit', 'pause usage', 'usage pause'.
 argument-hint: "[reset time like 10:20pm | duration like 74m]"
 ---
 
@@ -37,27 +33,27 @@ On exit 0 the script prints one JSON object:
 | `session_utilization` | Percent of the 5-hour window spent (null on override) |
 | `weekly_utilization` | Percent of the weekly window spent (null on override) |
 | `weekly_resets_at` | When the weekly window resets (null on override) |
-| `weekly_near_cap` | True when the weekly meter is at or past 90 percent |
+| `weekly_near_cap` | True when the weekly meter is at or past the warn threshold |
 
 On exit 2 the script prints `{"error": ...}`. Ask the user for a manual reset time via AskUserQuestion (offer clock-time and duration examples), then rerun with `--override`.
 
 ### Probe mechanism
 
-The resolver gets a bearer token from one of two sources and sends `GET https://api.anthropic.com/api/oauth/usage` with `Authorization: Bearer <token>` and `anthropic-beta: oauth-2025-04-20`. This is the same endpoint the interactive `/usage` panel reads. The response carries a `five_hour` bucket and a `seven_day` bucket, each with `utilization` (percent spent) and `resets_at`.
+`scripts/resolve_usage_window.py` is the source of truth for live probe behavior. Endpoint URL, header names/values, credential path and token keys, response bucket keys, stage sizing, and the weekly warn threshold all live in `scripts/usage_pause_constants/resolve_usage_window_constants.py` — read those modules for the current values; do not restate them here.
 
-Token sources, in order:
+In short: the resolver picks a bearer token, probes the OAuth usage endpoint the interactive `/usage` panel uses, and returns the session and weekly buckets with utilization and reset times. Token sources, in order:
 
-- The Claude Code CLI's OAuth access token in `~/.claude/.credentials.json` (`claudeAiOauth.accessToken`, honored only while its `expiresAt` sits in the future).
-- The session ingress token in the file named by the `CLAUDE_SESSION_INGRESS_TOKEN_FILE` environment variable, read when the credential file token is unavailable. Claude Code cloud sessions set this variable and omit the credential file.
+1. The Claude Code CLI's stored OAuth access token (honored only while unexpired).
+2. The session ingress bearer token file named by `CLAUDE_SESSION_INGRESS_TOKEN_FILE` (cloud sessions).
 
-Fallbacks, in order: no usable token from either source, a failed request, or a response with no readable `five_hour` reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are stale.
+Fallbacks, in order: both token sources unavailable (expired/unreadable credential and no ingress file), a failed request, or a response with no readable session-window reset time all end in exit 2 — the manual-override ask above. The manual path works with no probe at all, so the skill functions even when both token sources are unavailable.
 
 Why this probe and not the others:
 
 - The interactive `/usage` panel shows the same data but has no scriptable output.
 - `claude -p --output-format json` spends usage to answer and its metadata reports per-call token counts, not the account window clock.
 - `anthropic-ratelimit-*` response headers cover API-key Messages traffic, not the subscription session window, and reading them also costs a request.
-- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads its token sources.
+- Refreshing the OAuth token from a script is out of scope: token rotation would desync the refresh token the CLI has on disk and log the CLI out. The resolver only ever reads tokens (credential file or session ingress file).
 
 ## Weekly limit guard
 
@@ -70,7 +66,7 @@ Before the first sleep:
 1. List active recurring loops (CronList). Record each one's schedule and prompt, then cancel it (CronDelete). Carry the recorded list inside the wakeup prompts so the state survives every stage.
 2. Schedule the first stage with ScheduleWakeup, using the first duration in `stages_seconds` and the stage prompt template below.
 
-The stage plan keeps every stage at or under 58 minutes (3480 seconds, inside the 3600-second clamp) and ends with a roughly 2-minute tail stage so the final firing lands just past the reset. A leftover too short to stand alone folds into the tail.
+The stage plan (`stages_seconds` from the resolver) keeps every stage under the maximum stage length and ends with a short tail so the final firing lands just past the reset. Stage sizing constants live in `scripts/usage_pause_constants/resolve_usage_window_constants.py`; a leftover too short to stand alone folds into the tail.
 
 Every wakeup does exactly three things — ping, record, schedule — and dispatches no new work. The cache rationale: an unpinged idle agent left past the cache window resumes cold and re-reads its whole transcript, so pings run tighter than the cache lifetime and keep each agent's next real invocation cheap.
 
@@ -110,7 +106,7 @@ Fill each `<slot>` at schedule time: `<remaining_stage_durations>` is the tail o
 | `SKILL.md` | This flow: resolve, weekly guard, stage chain, templates |
 | `scripts/resolve_usage_window.py` | The window resolver and stage planner CLI |
 | `scripts/test_resolve_usage_window.py` | Behavioral tests for parsing, staging, token reading, extraction, CLI |
-| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, the session ingress token env var, stage sizing, thresholds, result keys |
+| `scripts/usage_pause_constants/resolve_usage_window_constants.py` | Endpoint, credential keys, stage sizing, thresholds, result keys |
 
 ## Gotchas
 

package/skills/bdd-protocol/CLAUDE.md

@@ -1,26 +0,0 @@
-# bdd-protocol
-
-**Trigger:** `/bdd-protocol`, "Example Mapping", "BDD anti-patterns", "§7.6", writing executable specifications, BDD scenario quality, "the one where" discovery examples.
-
-On-demand BDD depth layered on top of the always-on `<behavior_protocol>` in the system prompt. The skill adds the Example Mapping algorithm (Smart & Molak §6.4), the scenario quality catalog (§7.6), outside-in test layout, and solo BDD patterns.
-
-## Subdirectories
-
-| Directory | Role |
-|---|---|
-| `references/` | Loaded reference docs: Example Mapping algorithm and the anti-patterns catalog. |
-
-## Key files
-
-| File | Role |
-|---|---|
-| `SKILL.md` | Entry point. `@`-imports both reference files so they load with the skill. Lists authorities and scope boundaries. |
-| `references/example-mapping.md` | Example Mapping algorithm: core moves ("The one where …"), the chat algorithm for solo use, time-boxing guidance. Source: Smart & Molak §6.4. |
-| `references/anti-patterns.md` | §7.6 scenario quality catalog: anti-patterns to avoid and the criteria for a good scenario. |
-
-## What the skill adds
-
-The base `<behavior_protocol>` (Deliberate Discovery → Illustrate → Formulate → Automate) is always active. This skill adds depth only when:
-- The task needs Example Mapping steps or parking-lot question management.
-- Scenarios need the §7.6 quality bar applied.
-- Tests need outside-in layout using describe / when / should.