claude-dev-env 1.93.1 → 1.95.0

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.

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 |
+|---|---|---|
+| `/reviewer-gates` | Step 1 — gate external reviewers | opt-out, Copilot quota, Bugbot trigger decisions |
+| `/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/team-advisor/SKILL.md

@@ -29,21 +29,25 @@ the CLI fallback — using `team-advisor-agent` as the name and this session as
 the only consumer (skip the "who you are and your assignment" opener in each
 consult; a single-consumer session doesn't need it).
 
-**Grok host:** use the self-as-advisor path in the shared protocol: this
-session answers ENDORSE / CORRECTION / PLAN / STOP itself. Do not spawn a
-Claude `session-advisor` subagent and do not walk the Claude multi-tier
-ladder.
+**Grok host:** bind a max-tier Claude advisor through the shared CLI Claude-chain
+in the protocol (Fable high, then Opus max; `claude_chain_runner.py` walks
+`~/.claude/claude-chain.json` for account usage failover). Consult via
+`--resume <session_id>` on that bind. This session is the sole consumer of that
+CLI advisor; skip the multi-consumer opener. When the chain cannot bind or
+reply, fail closed and report to the user — do **not** answer ENDORSE /
+CORRECTION / PLAN / STOP as this Grok session.
 
 ## Constraints
 
-- One `team-advisor-agent` per session, owned by this session for its whole
-  lifecycle (spawn, drift-respawn, shutdown) — see
+- One advisor bind per session (`team-advisor-agent` on Claude; one CLI
+  `session_id` on Grok), owned by this session for its whole lifecycle
+  (spawn or CLI bind, drift re-bind, shutdown) — see
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md).
-- Never spawn the warm agent, or its CLI fallback, at a tier below this
-  session's own tier.
-- The warm agent (or its CLI equivalent) only answers. It never edits a
-  file, never runs a build or test, and never posts anything on the
-  session's behalf.
+- Never bind the advisor, or its CLI path, at a tier below the protocol floor
+  for this host (Claude: this session's own tier; Grok: Opus floor with Fable
+  first).
+- The advisor only answers. It never edits a file, never runs a build or
+  test, and never posts anything on the session's behalf.
 
 ## File Index