claude-dev-env 2.12.0 → 2.14.0

package/skills/rebase/CLAUDE.md

@@ -1,32 +1 @@
-# rebase
-
-Rebase a branch onto its base ref with verification gates that catch logically broken results before pushing.
-
-**Trigger:** `/rebase`, "rebase this branch", "PR has merge conflicts", "rebase onto main", force-push to update remote branch history.
-
-## Purpose
-
-The default failure mode for a rebase is shipping code that compiled but does not run. This skill prevents that by running real import checks, test collection, and symbol scans after every rebase — not just syntax validation.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — four phases (pre-rebase analysis, during rebase, verification gates, push). No companion files. |
-
-## Four phases
-
-| Phase | Key actions |
-|---|---|
-| 1 — Pre-rebase analysis | Resolve base via `gh pr view`, classify scenario (stacked/squash/long-lived), fetch fresh, scan commit messages for deleted/renamed symbols |
-| 2 — During rebase | Verify `--skip` with a diff, audit auto-merged files with `git diff --name-only --diff-filter=M ORIG_HEAD` |
-| 3 — Verification gates | `python -m compileall`, `pytest --collect-only -q`, targeted test run, reference scan for removals |
-| 4 — Push | Explicit authorization required; `--force-with-lease=<branch>:<sha>` only; verify mergeability after push |
-
-## Conventions
-
-- Force-push requires explicit operator authorization every time — auto mode does not bypass this.
-- `--force-with-lease=<branch>:<sha>` only; bare `--force` is refused.
-- Never force-push `main`, `master`, `release/*`, `production`, or any multi-author branch.
-- Symbol scans prefer Serena (`find_referencing_symbols`) then the Grep tool, then shell grep as a last resort.
-- `ORIG_HEAD` is the correct ref for auto-merged file audits mid-rebase; `HEAD@{1}` shifts per step.
+@AGENTS.md

package/skills/recall/AGENTS.md

@@ -0,0 +1,30 @@
+# recall
+
+Retrieves prior session context and decisions from the Obsidian vault for the current project.
+
+**Trigger:** `/recall [search query or project name]`.
+
+## Purpose
+
+Surfaces relevant session reports, decision notes, and research from the Obsidian vault before starting work. Prevents repeating decisions already made or missing known gotchas.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (resolve query, frontmatter search, content search, read top matches, present with attribution, handle no results). No companion files. |
+
+## How the skill runs
+
+1. Uses `$ARGUMENTS` as the search query, or infers the project name from conversation context.
+2. Searches by frontmatter first (`mcp__obsidian__search_notes` with `searchFrontmatter: true`) to catch session reports and decision notes tagged with the project.
+3. Falls back to content keyword search when frontmatter search returns few results.
+4. Reads the top 3 most relevant notes via `mcp__obsidian__read_note`, preferring recent notes and decision summaries over raw research.
+5. Reports each note with its path, date, relevant excerpts, and whether any decisions are marked `status: Superseded`.
+6. States clearly when no vault history exists — never infers or invents history.
+
+## Conventions
+
+- `disable-model-invocation: true` is not set; this skill does invoke the model to synthesize results.
+- The skill is read-only: it never writes to the vault.
+- Companion to `/remember` (which writes decisions) and `/session-log` (which writes session reports).

package/skills/recall/CLAUDE.md

@@ -1,30 +1 @@
-# recall
-
-Retrieves prior session context and decisions from the Obsidian vault for the current project.
-
-**Trigger:** `/recall [search query or project name]`.
-
-## Purpose
-
-Surfaces relevant session reports, decision notes, and research from the Obsidian vault before starting work. Prevents repeating decisions already made or missing known gotchas.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — six steps (resolve query, frontmatter search, content search, read top matches, present with attribution, handle no results). No companion files. |
-
-## How the skill runs
-
-1. Uses `$ARGUMENTS` as the search query, or infers the project name from conversation context.
-2. Searches by frontmatter first (`mcp__obsidian__search_notes` with `searchFrontmatter: true`) to catch session reports and decision notes tagged with the project.
-3. Falls back to content keyword search when frontmatter search returns few results.
-4. Reads the top 3 most relevant notes via `mcp__obsidian__read_note`, preferring recent notes and decision summaries over raw research.
-5. Reports each note with its path, date, relevant excerpts, and whether any decisions are marked `status: Superseded`.
-6. States clearly when no vault history exists — never infers or invents history.
-
-## Conventions
-
-- `disable-model-invocation: true` is not set; this skill does invoke the model to synthesize results.
-- The skill is read-only: it never writes to the vault.
-- Companion to `/remember` (which writes decisions) and `/session-log` (which writes session reports).
+@AGENTS.md

package/skills/remember/AGENTS.md

@@ -0,0 +1,31 @@
+# remember
+
+Saves a decision, gotcha, or architectural choice to the Obsidian vault as a structured note.
+
+**Trigger:** User-initiated only. `/remember [what to remember]`.
+
+## Purpose
+
+Writes a decision, fact, procedure, or gotcha to `decisions/[Project] - [Short Title].md` in the Obsidian vault. Each note carries structured frontmatter and a body shaped by its type, making it searchable and readable via `/recall`.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — six steps (parse input, classify type, infer project, generate title, write to vault, confirm). No companion files. |
+
+## Four note types
+
+| Type | Body format |
+|---|---|
+| `decision` | Decision + Reasoning + Alternatives + Consequences |
+| `gotcha` | Gotcha + Symptom + Fix |
+| `procedural` | 1–3 clear sentences describing the how-to |
+| `fact` | 1–3 clear sentences stating the fact |
+
+## Conventions
+
+- `disable-model-invocation: true` is set — runs without a secondary LLM call.
+- Writes via `mcp__obsidian__write_note` only; never edits existing notes.
+- Path pattern: `decisions/[Project] - [Short Title].md`.
+- Companion to `/recall` (reads vault) and `/session-log` (triggers decision extraction at session end).

package/skills/remember/CLAUDE.md

@@ -1,31 +1 @@
-# remember
-
-Saves a decision, gotcha, or architectural choice to the Obsidian vault as a structured note.
-
-**Trigger:** User-initiated only. `/remember [what to remember]`.
-
-## Purpose
-
-Writes a decision, fact, procedure, or gotcha to `decisions/[Project] - [Short Title].md` in the Obsidian vault. Each note carries structured frontmatter and a body shaped by its type, making it searchable and readable via `/recall`.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — six steps (parse input, classify type, infer project, generate title, write to vault, confirm). No companion files. |
-
-## Four note types
-
-| Type | Body format |
-|---|---|
-| `decision` | Decision + Reasoning + Alternatives + Consequences |
-| `gotcha` | Gotcha + Symptom + Fix |
-| `procedural` | 1–3 clear sentences describing the how-to |
-| `fact` | 1–3 clear sentences stating the fact |
-
-## Conventions
-
-- `disable-model-invocation: true` is set — runs without a secondary LLM call.
-- Writes via `mcp__obsidian__write_note` only; never edits existing notes.
-- Path pattern: `decisions/[Project] - [Short Title].md`.
-- Companion to `/recall` (reads vault) and `/session-log` (triggers decision extraction at session end).
+@AGENTS.md

package/skills/reviews/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: reviews
+description: >-
+  Review a pull request or code change for code health. Use when a user asks to
+  "code review", "review this PR", or "review this change".
+---
+
+# Code Review Guide
+
+Use this guide to evaluate a pull request or code change. Apply the repository's
+the repository's checked-in review contract and `CODE_RULES.md` as its project-specific quality rubric.
+
+## Review Judgment
+
+Review work supports code health. Frame each conclusion around observable
+behavior, maintainability, risk, and the change's intended outcome.
+
+- Use technical evidence and repository conventions to resolve trade-offs.
+- Mark a required change when it materially affects correctness, security,
+  reliability, data integrity, maintainability, or the stated behavior.
+- Mark optional improvement as `Consider` or `Nit` so the author can prioritize
+  the work accurately.
+- Accept an evidence-backed explanation when it satisfies the applicable
+  quality rubric.
+
+## Evaluation Criteria
+
+Evaluate the changed code and the surrounding context for:
+
+- Design fit, interfaces, complexity, and future maintenance cost.
+- Functional behavior, user impact, edge cases, concurrency, privacy,
+  security, and accessibility where applicable.
+- Tests that exercise the changed behavior and distinguish regressions.
+- Names, comments, documentation, and style against the repository rubric and
+  the applicable language guide.
+- Migration, configuration, compatibility, and operational effects.
+
+## Review Workflow
+
+1. Read the pull request description and identify the intended outcome.
+2. Inspect the changed code, relevant callers, and the surrounding design.
+3. Run or assess relevant verification and identify its coverage boundaries.
+4. Write each finding with the affected location, observed effect, expected
+   outcome, and supporting evidence.
+5. State the reviewed scope, verification performed, and any remaining
+   uncertainty in the review output.
+
+Use the [comment guide](../comments/SKILL.md#writing-useful-review-comments)
+for finding wording and the [description guide](../descriptions/SKILL.md#reviewing-a-description)
+for description content.
+
+## Execution Support
+
+Use available runners for inspection, verification, and repository navigation.
+This guide supplies the judgment criteria and the corresponding guide anchors.
+
+## Review Responsiveness
+
+Begin a requested review at the next clean work boundary. Provide a useful
+response promptly, including the completed scope and the remaining work when
+context gathering continues.
+
+Review the highest-impact design questions early. A focused response gives the
+author a clear next action while the full assessment continues.
+
+## Resolving Disagreements
+
+Consolidate a disagreement into one thread that records the relevant context,
+technical rationale, and desired decision. Reassess the finding against the
+repository rubric and accept a sound alternative that meets the same outcome.
+
+Seek a maintainer or lead decision when the discussion requires ownership or
+product direction beyond the available evidence. Keep the resulting decision in
+the pull request record.
+
+## Related Guides
+
+- Use [comments](../comments/SKILL.md#when-to-use-this-guide) to draft or answer
+  review feedback.
+- Use [descriptions](../descriptions/SKILL.md#when-to-use-this-guide) to prepare
+  or assess pull request context.
+- Use [emergencies](../emergencies/SKILL.md#emergency-classification) to classify
+  an urgent production change.
+- Use [small-cl](../small-cl/SKILL.md#when-to-use-this-guide) to focus or split
+  a change that exceeds a clear review boundary.

package/skills/session-log/AGENTS.md

@@ -0,0 +1,32 @@
+# session-log
+
+Logs a session report as a self-contained HTML page in the Obsidian vault, publishes it with the `Artifact` tool, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
+
+**Trigger:** `/session-log`, "journal this session", "log this work", "session report", "save session", "capture session", "document what we did".
+
+## Purpose
+
+Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, HTML composition and publishing, decision extraction, and folder hygiene.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — six steps, gotchas, backend detection, run-and-report checklist. |
+| `templates/frontmatter.md` | The session-page frontmatter contract and the Step 3 notes block. |
+
+## Six steps
+
+1. **Backend detection** — headless vault (`ob --version` + `OBSIDIAN_VAULT_PATH`) then local vault (`~/.claude/vault/`). Session number from `[N]. *.html` and `[N]. *.md` files in the project folder.
+2. **Session metadata** — project name, session number, session ID from `CLAUDE_CODE_SESSION_ID`, date, title.
+3. **Compose and publish via the Artifact tool** — loads the `artifact-design` skill first, designs the shape for the session's character (e.g., a PR-writeup shape for feature builds, a timeline shape for incidents), writes the HTML, then publishes it with the `Artifact` tool using the fixed favicon `📓`.
+4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line, then redeploy via `Artifact` on the same `file_path` so the URL stays the same.
+5. **Decision extraction** — scans conversation for unrecorded decisions; prompts user via `AskUserQuestion` before invoking `/remember`.
+6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues and redeploys via `Artifact`.
+
+## Conventions
+
+- Session reports use HTML — the Artifact tool publishes HTML or Markdown, and HTML gives the report designer more visual structure.
+- `write_existing_file_blocker` rejects Write on existing paths — use Edit for all vault-context updates.
+- The `Artifact` tool redeploys to the same URL on repeat calls with the same `file_path` within the current run — edits made in steps 3 and 5 to the session created this run never mint a new URL.
+- Final step copies `/rename [Project] - [Primary Outcome]` to the clipboard via `pwsh Set-Clipboard`.

package/skills/session-log/CLAUDE.md

@@ -1,32 +1 @@
-# session-log
-
-Logs a session report as a self-contained HTML page in the Obsidian vault, publishes it with the `Artifact` tool, extracts unrecorded decisions, tidies the project session folder, and outputs a `/rename` command.
-
-**Trigger:** `/session-log`, "journal this session", "log this work", "session report", "save session", "capture session", "document what we did".
-
-## Purpose
-
-Produces a self-contained HTML session report shaped to the session's character (feature build, incident, research, etc.) rather than a fixed template. The skill owns the vault path, session numbering, frontmatter contract, HTML composition and publishing, decision extraction, and folder hygiene.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | Hub — six steps, gotchas, backend detection, run-and-report checklist. |
-| `templates/frontmatter.md` | The session-page frontmatter contract and the Step 3 notes block. |
-
-## Six steps
-
-1. **Backend detection** — headless vault (`ob --version` + `OBSIDIAN_VAULT_PATH`) then local vault (`~/.claude/vault/`). Session number from `[N]. *.html` and `[N]. *.md` files in the project folder.
-2. **Session metadata** — project name, session number, session ID from `CLAUDE_CODE_SESSION_ID`, date, title.
-3. **Compose and publish via the Artifact tool** — loads the `artifact-design` skill first, designs the shape for the session's character (e.g., a PR-writeup shape for feature builds, a timeline shape for incidents), writes the HTML, then publishes it with the `Artifact` tool using the fixed favicon `📓`.
-4. **Vault context tracking** — two Edit calls set `vault_context_retrieved` and append a vault-context line, then redeploy via `Artifact` on the same `file_path` so the URL stays the same.
-5. **Decision extraction** — scans conversation for unrecorded decisions; prompts user via `AskUserQuestion` before invoking `/remember`.
-6. **Session tidy** — audits `.html` files in the project folder for naming and frontmatter; auto-fixes minor issues and redeploys via `Artifact`.
-
-## Conventions
-
-- Session reports use HTML — the Artifact tool publishes HTML or Markdown, and HTML gives the report designer more visual structure.
-- `write_existing_file_blocker` rejects Write on existing paths — use Edit for all vault-context updates.
-- The `Artifact` tool redeploys to the same URL on repeat calls with the same `file_path` within the current run — edits made in steps 3 and 5 to the session created this run never mint a new URL.
-- Final step copies `/rename [Project] - [Primary Outcome]` to the clipboard via `pwsh Set-Clipboard`.
+@AGENTS.md

package/skills/session-tidy/AGENTS.md

@@ -0,0 +1,36 @@
+# session-tidy
+
+Audits, cleans, and consolidates session logs in the Obsidian vault — fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries.
+
+**Trigger:** `/session-tidy`, "tidy sessions", "clean up session logs", "session audit".
+
+## Purpose
+
+Maintenance utility for the `sessions/[Project]/` vault directories. Enforces the session-log format contract, moves uncategorized files into project subfolders, and generates `Summary.md` rollup files for projects with 3+ sessions.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete skill — four phases (preflight, audit, propose changes, execute + verify). No companion files. |
+
+## Format contract enforced
+
+- **Path:** `sessions/[Project]/[N]. [Title].md`
+- **Frontmatter:** `type`, `project`, `session`, `date`, `status`, `blocked`, `tags` — all needed.
+- **Status rules:** `completed` + `blocked: true` is contradictory; `in-progress` or `blocked` older than 7 days is stale.
+- **Content:** outcome-oriented `###` headers with one emoji; no play-by-play narration.
+
+## Four phases
+
+1. **Preflight** — resolve backend (headless vault, Obsidian MCP, or local vault).
+2. **Audit** — check each file for naming, frontmatter completeness, status coherence, orphaned next-steps, and categorization.
+3. **Propose changes** — report findings; wait for user approval before changing anything.
+4. **Execute + verify** — rename files, fix frontmatter, update statuses, clean orphaned next-steps, generate `Summary.md` rollups.
+
+## Conventions
+
+- `disable-model-invocation: true` is set.
+- Changes need explicit user approval from Phase 2's report — the skill never auto-applies without approval.
+- Companion to `/session-log` (creates sessions) and `/recall` (reads vault).
+- `/session-tidy` targets Markdown session format; HTML sessions from `/session-log` may be mis-audited or get incorrect rename proposals.

package/skills/session-tidy/CLAUDE.md

@@ -1,36 +1 @@
-# session-tidy
-
-Audits, cleans, and consolidates session logs in the Obsidian vault — fixes format drift, resolves orphaned next-steps, updates stale statuses, and generates project rollup summaries.
-
-**Trigger:** `/session-tidy`, "tidy sessions", "clean up session logs", "session audit".
-
-## Purpose
-
-Maintenance utility for the `sessions/[Project]/` vault directories. Enforces the session-log format contract, moves uncategorized files into project subfolders, and generates `Summary.md` rollup files for projects with 3+ sessions.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `SKILL.md` | The complete skill — four phases (preflight, audit, propose changes, execute + verify). No companion files. |
-
-## Format contract enforced
-
-- **Path:** `sessions/[Project]/[N]. [Title].md`
-- **Frontmatter:** `type`, `project`, `session`, `date`, `status`, `blocked`, `tags` — all needed.
-- **Status rules:** `completed` + `blocked: true` is contradictory; `in-progress` or `blocked` older than 7 days is stale.
-- **Content:** outcome-oriented `###` headers with one emoji; no play-by-play narration.
-
-## Four phases
-
-1. **Preflight** — resolve backend (headless vault, Obsidian MCP, or local vault).
-2. **Audit** — check each file for naming, frontmatter completeness, status coherence, orphaned next-steps, and categorization.
-3. **Propose changes** — report findings; wait for user approval before changing anything.
-4. **Execute + verify** — rename files, fix frontmatter, update statuses, clean orphaned next-steps, generate `Summary.md` rollups.
-
-## Conventions
-
-- `disable-model-invocation: true` is set.
-- Changes need explicit user approval from Phase 2's report — the skill never auto-applies without approval.
-- Companion to `/session-log` (creates sessions) and `/recall` (reads vault).
-- `/session-tidy` targets Markdown session format; HTML sessions from `/session-log` may be mis-audited or get incorrect rename proposals.
+@AGENTS.md

package/skills/skill-builder/AGENTS.md

@@ -0,0 +1,49 @@
+# skill-builder
+
+Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via the `skill-writer-agent` agent, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
+
+**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog, deterministic skill scripts.
+
+## Purpose
+
+Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `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/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
+| `references/description-field.md` | Description as trigger catalog (not story prose) |
+| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; no markdown checkbox boards |
+| `references/self-audit-checklist.md` | Post-build audit task seeds (TaskCreate / TodoWrite) |
+| `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 trigger-catalog audit and final validation (5 steps) |
+| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
+
+## Subdirectories
+
+| Directory | Purpose |
+|---|---|
+| `references/` | Best-practice specs and the audit checklist |
+| `workflows/` | Step-by-step workflows for each lifecycle phase |
+| `templates/` | Reusable templates for skill artifacts |
+
+## Routing
+
+- **New skill** → `workflows/new-skill.md`
+- **Improve existing** → `workflows/improve-skill.md`
+- **Final polish only** → `workflows/polish-skill.md`
+- **Ambiguous** → ask the user which one applies
+
+## Conventions
+
+- Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
+- Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
+- `skill-builder` orchestrates; the `skill-writer-agent` agent authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, 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/CLAUDE.md

@@ -1,49 +1 @@
-# skill-builder
-
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via the `skill-writer-agent` agent, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
-
-**Trigger:** build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity, description trigger catalog, deterministic skill scripts.
-
-## Purpose
-
-Enforces craft standards for new and existing skills. For quick one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `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/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
-| `references/description-field.md` | Description as trigger catalog (not story prose) |
-| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; no markdown checkbox boards |
-| `references/self-audit-checklist.md` | Post-build audit task seeds (TaskCreate / TodoWrite) |
-| `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 trigger-catalog audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
-
-## Subdirectories
-
-| Directory | Purpose |
-|---|---|
-| `references/` | Best-practice specs and the audit checklist |
-| `workflows/` | Step-by-step workflows for each lifecycle phase |
-| `templates/` | Reusable templates for skill artifacts |
-
-## Routing
-
-- **New skill** → `workflows/new-skill.md`
-- **Improve existing** → `workflows/improve-skill.md`
-- **Final polish only** → `workflows/polish-skill.md`
-- **Ambiguous** → ask the user which one applies
-
-## Conventions
-
-- Every build ends with the self-audit at `references/self-audit-checklist.md`; fix failures before delivery.
-- Modularity items, description trigger-catalog items, and deterministic-element classification are mandatory on every delivery.
-- `skill-builder` orchestrates; the `skill-writer-agent` agent authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, 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.
+@AGENTS.md

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

@@ -0,0 +1,25 @@
+# skill-builder/references
+
+Best-practice specifications and the mandatory self-audit checklist for the `/skill-builder` skill.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `self-audit-checklist.md` | Audit task seeds after every build, improve, or polish. Register via TaskCreate / TodoWrite. |
+| `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. |
+| `deterministic-elements.md` | Classify process steps; deterministic ones ship as code, task seeds, or fixed artifacts under CODE_RULES. |
+| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer-agent. |
+| `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
+
+## Conventions
+
+- 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.
+- Load `deterministic-elements.md` during Gather, when prose-as-code is diagnosed, and on polish structure audit.
+- `thariq-x-post-skills.json` is source reference data, not executable content.

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

@@ -1,25 +1 @@
-# skill-builder/references
-
-Best-practice specifications and the mandatory self-audit checklist for the `/skill-builder` skill.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `self-audit-checklist.md` | Audit task seeds after every build, improve, or polish. Register via TaskCreate / TodoWrite. |
-| `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. |
-| `deterministic-elements.md` | Classify process steps; deterministic ones ship as code, task seeds, or fixed artifacts under CODE_RULES. |
-| `delegation-map.md` | Subagent handoff patterns and transcript guidance for skill-builder → skill-writer-agent. |
-| `thariq-x-post-skills.json` | Source reference data from Anthropic lessons on building Claude Code skills. |
-
-## Conventions
-
-- 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.
-- Load `deterministic-elements.md` during Gather, when prose-as-code is diagnosed, and on polish structure audit.
-- `thariq-x-post-skills.json` is source reference data, not executable content.
+@AGENTS.md

package/skills/skill-builder/references/deterministic-elements.md

@@ -112,7 +112,7 @@ The seed list file lives under `reference/` (or is a named section of an existin
 
 ## CODE_RULES bar (every code file in the skill)
 
-Skill scripts are production code. They obey the same rules as the rest of the repo (`docs/CODE_RULES.md` / root `AGENTS.md`), including:
+Skill scripts are production code. They obey the same rules as the rest of the repo (`docs/CODE_RULES.md`), including:
 
 - **Named constants** — no bare magic numbers/strings in function bodies; skill-local values live in a `*_constants/` package the script imports.
 - **Types** — parameters and returns annotated; no bare `Any` / untyped escape hatches.

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

@@ -0,0 +1,14 @@
+# skill-builder/templates
+
+Reusable templates for skill-building artifacts.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `gap-analysis.md` | Template for gaps, composition plan, description triggers, and deterministic-elements inventory. Used in new-skill Gather and improve diagnosis. |
+
+## Conventions
+
+- Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
+- Composition plan, Description triggers, and Deterministic Elements Inventory sections are required before Write on a new skill.

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

@@ -1,14 +1 @@
-# skill-builder/templates
-
-Reusable templates for skill-building artifacts.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `gap-analysis.md` | Template for gaps, composition plan, description triggers, and deterministic-elements inventory. Used in new-skill Gather and improve diagnosis. |
-
-## Conventions
-
-- Fill the template inline during the workflow; do not commit completed gap analyses to this directory.
-- Composition plan, Description triggers, and Deterministic Elements Inventory sections are required before Write on a new skill.
+@AGENTS.md

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

@@ -0,0 +1,19 @@
+# skill-builder/workflows
+
+Step-by-step workflow files for each skill lifecycle phase, loaded on demand by `SKILL.md` routing.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via the skill-writer-agent agent, self-audit, deliver. |
+| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
+| `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
+
+## 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 verification step.
+- New and improve load `skill-modularity.md`, `description-field.md`, and `deterministic-elements.md` when gathering or diagnosing.
+- Polish Step 1 is the dedicated description rewrite pass; Step 2 covers structure, modularity, and deterministic placement.
+- Load only the workflow that matches the active task; the other two stay out of context.

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

@@ -1,19 +1 @@
-# skill-builder/workflows
-
-Step-by-step workflow files for each skill lifecycle phase, loaded on demand by `SKILL.md` routing.
-
-## Key files
-
-| File | Purpose |
-|---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via the skill-writer-agent agent, self-audit, deliver. |
-| `improve-skill.md` | Observation-first improve: diagnose activation/modularity/quality/deterministic prose, targeted fix, re-audit. |
-| `polish-skill.md` | Description trigger-catalog audit; progressive disclosure + modularity + deterministic audit; task-seeded self-audit. |
-
-## 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 verification step.
-- New and improve load `skill-modularity.md`, `description-field.md`, and `deterministic-elements.md` when gathering or diagnosing.
-- Polish Step 1 is the dedicated description rewrite pass; Step 2 covers structure, modularity, and deterministic placement.
-- Load only the workflow that matches the active task; the other two stay out of context.
+@AGENTS.md