claude-dev-env 2.3.0 → 2.5.0

package/skills/prototype/scripts/test_probe_sandbox_safety.py

@@ -0,0 +1,284 @@
+"""Tests for the sandbox safety-hook probe.
+
+The block-detection unit tests drive fixture hook scripts, and the
+integration tests point a settings file at the real installed safety hooks
+to prove they block their probe payloads end to end.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from prototype_scripts_constants.config.build_sandbox_settings_constants import (
+    ALL_SAFETY_HOOK_SCRIPT_BASENAMES,
+    COMMAND_KEY,
+    HOOKS_KEY,
+    MATCHER_KEY,
+    PRE_TOOL_USE_KEY,
+)
+from prototype_scripts_constants.config.probe_sandbox_safety_constants import (
+    DESTRUCTIVE_PROBE_COMMAND,
+    ENVELOPE_TOOL_INPUT_KEY,
+    ENVELOPE_TOOL_NAME_KEY,
+    PII_PROBE_TOKEN_PREFIX,
+    PII_PROBE_TOOL_NAME,
+    PROBE_FAILURE_EXIT_CODE,
+    PROBE_SUCCESS_EXIT_CODE,
+    TOOL_INPUT_COMMAND_KEY,
+    TOOL_INPUT_CONTENT_KEY,
+)
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+PROBE_PATH = SCRIPTS_DIRECTORY / "probe_sandbox_safety.py"
+HOOKS_BLOCKING_DIRECTORY = SCRIPTS_DIRECTORY.parents[2] / "hooks" / "blocking"
+
+PII_HOOK_BASENAME = ALL_SAFETY_HOOK_SCRIPT_BASENAMES[0]
+DESTRUCTIVE_HOOK_BASENAME = ALL_SAFETY_HOOK_SCRIPT_BASENAMES[1]
+
+DENY_HOOK_SOURCE = (
+    "import json, sys\n"
+    "sys.stdout.write(json.dumps("
+    '{"hookSpecificOutput": {"permissionDecision": "deny"}}))\n'
+)
+ASK_HOOK_SOURCE = (
+    "import json, sys\n"
+    "sys.stdout.write(json.dumps("
+    '{"hookSpecificOutput": {"permissionDecision": "ask"}}))\n'
+)
+ALLOW_HOOK_SOURCE = "import sys\nsys.exit(0)\n"
+
+
+def load_probe_module() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("probe_sandbox_safety", PROBE_PATH)
+    assert spec is not None
+    assert spec.loader is not None
+    probe_module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(probe_module)
+    return probe_module
+
+
+def quoted_command(script_path: Path) -> str:
+    return f'"{sys.executable}" "{script_path}"'
+
+
+def real_hook_settings_document() -> dict:
+    pii_hook_path = HOOKS_BLOCKING_DIRECTORY / PII_HOOK_BASENAME
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    return {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+
+
+def real_hook_deny_mode_settings_document() -> dict:
+    settings_document = real_hook_settings_document()
+    settings_document["env"] = {"CLAUDE_DESTRUCTIVE_DENY_MODE": "1"}
+    return settings_document
+
+
+def write_settings_file(tmp_path: Path, settings_document: dict) -> Path:
+    settings_path = tmp_path / "sandbox-settings.json"
+    settings_path.write_text(json.dumps(settings_document), encoding="utf-8")
+    return settings_path
+
+
+def test_settings_environment_overrides_reads_the_env_block() -> None:
+    probe = load_probe_module()
+    environment_overrides = probe.settings_environment_overrides(
+        real_hook_deny_mode_settings_document()
+    )
+    assert environment_overrides == {"CLAUDE_DESTRUCTIVE_DENY_MODE": "1"}
+
+
+def test_settings_environment_overrides_empty_without_an_env_block() -> None:
+    probe = load_probe_module()
+    environment_overrides = probe.settings_environment_overrides(
+        real_hook_settings_document()
+    )
+    assert environment_overrides == {}
+
+
+def test_main_exits_zero_when_the_real_destructive_hook_denies_in_deny_mode(
+    tmp_path: Path,
+) -> None:
+    probe = load_probe_module()
+    settings_path = write_settings_file(
+        tmp_path, real_hook_deny_mode_settings_document()
+    )
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_SUCCESS_EXIT_CODE
+
+
+def test_pii_basename_probe_payload_carries_the_secret() -> None:
+    probe = load_probe_module()
+    probe_payload = probe.build_probe_payload_for_basename(PII_HOOK_BASENAME)
+    assert probe_payload[ENVELOPE_TOOL_NAME_KEY] == PII_PROBE_TOOL_NAME
+    content = probe_payload[ENVELOPE_TOOL_INPUT_KEY][TOOL_INPUT_CONTENT_KEY]
+    assert PII_PROBE_TOKEN_PREFIX in content
+
+
+def test_destructive_basename_probe_payload_carries_the_command() -> None:
+    probe = load_probe_module()
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    command = probe_payload[ENVELOPE_TOOL_INPUT_KEY][TOOL_INPUT_COMMAND_KEY]
+    assert command == DESTRUCTIVE_PROBE_COMMAND
+
+
+def test_find_hook_command_for_basename_returns_the_matching_command() -> None:
+    probe = load_probe_module()
+    settings_document = real_hook_settings_document()
+    command = probe.find_hook_command_for_basename(settings_document, PII_HOOK_BASENAME)
+    assert command is not None
+    assert PII_HOOK_BASENAME in command
+    assert probe.find_hook_command_for_basename(settings_document, "absent.py") is None
+
+
+def test_parse_command_argv_splits_and_unquotes_the_command() -> None:
+    probe = load_probe_module()
+    command_argv = probe.parse_command_argv('"/usr/bin/python" "/a/b hook.py"')
+    assert command_argv == ["/usr/bin/python", "/a/b hook.py"]
+
+
+def test_hook_blocks_probe_reports_true_for_a_deny_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    deny_hook_path = tmp_path / "deny_hook.py"
+    deny_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(deny_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is True
+
+
+def test_hook_blocks_probe_reports_false_for_an_ask_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    ask_hook_path = tmp_path / "ask_hook.py"
+    ask_hook_path.write_text(ASK_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(ask_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is False
+
+
+def test_hook_blocks_probe_reports_false_for_an_allow_hook(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    allow_hook_path = tmp_path / "allow_hook.py"
+    allow_hook_path.write_text(ALLOW_HOOK_SOURCE, encoding="utf-8")
+    command_argv = [sys.executable, str(allow_hook_path)]
+    probe_payload = probe.build_probe_payload_for_basename(DESTRUCTIVE_HOOK_BASENAME)
+    assert probe.hook_blocks_probe(command_argv, probe_payload, {}) is False
+
+
+def test_probe_safety_hook_blocks_against_the_real_pii_hook() -> None:
+    probe = load_probe_module()
+    settings_document = real_hook_settings_document()
+    assert probe.probe_safety_hook(settings_document, PII_HOOK_BASENAME) is True
+
+
+def test_main_exits_three_when_the_real_destructive_hook_only_asks(
+    tmp_path: Path,
+) -> None:
+    probe = load_probe_module()
+    settings_path = write_settings_file(tmp_path, real_hook_settings_document())
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_zero_when_both_real_hooks_hard_deny(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    deny_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    deny_pii_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    deny_destructive_hook_path = tmp_path / DESTRUCTIVE_HOOK_BASENAME
+    deny_destructive_hook_path.write_text(DENY_HOOK_SOURCE, encoding="utf-8")
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(deny_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [
+                        {COMMAND_KEY: quoted_command(deny_destructive_hook_path)}
+                    ],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_SUCCESS_EXIT_CODE
+
+
+def test_main_exits_three_when_a_hook_allows(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    allow_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    allow_pii_hook_path.write_text(ALLOW_HOOK_SOURCE, encoding="utf-8")
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(allow_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_the_settings_file_is_absent(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    absent_settings_path = tmp_path / "does-not-exist.json"
+    exit_code = probe.main(["--settings", str(absent_settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_the_settings_file_is_invalid_json(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    settings_path = tmp_path / "sandbox-settings.json"
+    settings_path.write_text("{not valid json", encoding="utf-8")
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE
+
+
+def test_main_exits_three_when_a_hook_script_is_bogus(tmp_path: Path) -> None:
+    probe = load_probe_module()
+    bogus_pii_hook_path = tmp_path / PII_HOOK_BASENAME
+    destructive_hook_path = HOOKS_BLOCKING_DIRECTORY / DESTRUCTIVE_HOOK_BASENAME
+    settings_document = {
+        HOOKS_KEY: {
+            PRE_TOOL_USE_KEY: [
+                {
+                    MATCHER_KEY: "Write",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(bogus_pii_hook_path)}],
+                },
+                {
+                    MATCHER_KEY: "Bash",
+                    HOOKS_KEY: [{COMMAND_KEY: quoted_command(destructive_hook_path)}],
+                },
+            ]
+        }
+    }
+    settings_path = write_settings_file(tmp_path, settings_document)
+    exit_code = probe.main(["--settings", str(settings_path)])
+    assert exit_code == PROBE_FAILURE_EXIT_CODE

package/skills/prototype/workflows/promotion.md

@@ -0,0 +1,27 @@
+# Promotion workflow (Phase 2)
+
+Turn a successful proof-of-concept into a real, verified change. Run every step in the normal, fully-hooked session — never inside the `--bare` sandbox. The sandbox produced a reference build; promotion re-verifies it to standard and often rewrites parts of it.
+
+## Seed the task list first
+
+Register every item in `reference/promotion-tasks.md` as a session task (`TaskCreate`, or `TodoWrite` if that is the host tool). Work only from the task list. Mark each complete with evidence — a command result, a path, a verdict, or a skill's return.
+
+## The clean-room protocol
+
+The task seeds carry the full ordered detail. The shape:
+
+1. **Confirm** the POC is worth promoting and the user wants it shipped.
+2. **Fresh branch** off freshly-fetched `origin/main` via `fresh-branch` — clean history, based on live upstream.
+3. **Bring content as an uncommitted diff.** Copy the POC's file changes into the new branch's working tree. Do not cherry-pick or merge the sandbox commits; the sandbox history stays behind.
+4. **Cleanup.** Remove scratch files, debug dumps, and temp helpers the POC created (`cleanup-temp-files` rule).
+5. **Privacy sweep** via `privacy-hygiene` over the diff.
+6. **Verify** with the `code-verifier` agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../../orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — in a fresh context. This is where standards re-engage. Expect findings and a repair loop — the POC was un-TDD'd.
+7. **Commit and PR.** Only on a clean verdict, run `/commit`, then open a draft PR per the `git-workflow` rule.
+8. **State the honest limitations** from `reference/honest-limitations.md` in the PR body or to the user.
+9. **Converge** by handing the PR to `autoconverge` by default; use `pr-converge` for paced ticks or `bugteam` for an open-loop audit.
+
+## Why the clean room, not a push
+
+`code_rules_enforcer` is a write-time Write/Edit gate. Content that lands through `git apply`, `git checkout`, or cherry-pick never passes through it, so pushing the sandbox branch would ship code the rule engine never saw, carrying sandbox scratch along with it. Standards re-engage through the `code-verifier` agent, the `privacy-hygiene` sweep, and the PR review — not through a write-time hook. Steps 4-6 are hard gates: the honest claim on promoted POC code is code-verifier-passed, privacy-swept, review-passed, with TDD ordering waived.
+
+The `verified_commit_gate` hook is the backstop under all of this — it refuses a commit or push with no minted verdict — but the clean-room steps are the mechanism, not the gate firing.

package/skills/prototype/workflows/sandbox.md

@@ -0,0 +1,35 @@
+# Sandbox workflow (Phase 1)
+
+Stand up an isolated worktree where a hookless agent builds a proof-of-concept with zero standards friction. Only two safety gates stay live: personal-data blocking and destructive-command blocking.
+
+## Step 1 — Isolated worktree
+
+Invoke the `fresh-branch` skill to create a worktree off `origin/main`. Keep the returned `worktree_path` and `base_commit` for the promotion phase. If `fresh-branch` is not installed, stop with the refusal line from `SKILL.md`.
+
+## Step 2 — Minimal safety settings
+
+Run `scripts/build_sandbox_settings.py --out <worktree>/.prototype-sandbox-settings.json`.
+
+It reads the live `~/.claude/settings.json`, resolves each safety hook's command (the correct interpreter and absolute path for this machine), and registers it on the matchers the sandbox needs — personal-data on Write, Edit, MultiEdit, and Bash; destructive-command on Bash. The write file carries only those two gates, plus an `env` block that sets `CLAUDE_DESTRUCTIVE_DENY_MODE`, so the destructive gate hard-denies a match. A hard deny holds under `--dangerously-skip-permissions`; an `ask` there is auto-resolved.
+
+- Exit 0 → continue with the printed settings path.
+- Exit 2 → one of the two safety hooks could not be resolved from the live settings. Stop; the sandbox cannot be contained without both. Report which one is missing.
+
+## Step 3 — Prove containment
+
+Run `scripts/probe_sandbox_safety.py --settings <settings path>`.
+
+It feeds each safety hook a payload the hook is proven to block and confirms a hard-deny decision — the block that holds even under `--dangerously-skip-permissions`, unlike an `ask` prompt the flag auto-resolves. It runs each hook under the settings' `env` block, so the destructive gate runs in deny mode, the same way the launched session runs it.
+
+- Exit 0 → both gates hard-deny their probe; the sandbox is contained.
+- Exit 3 → a gate allowed its probe, returned an `ask`, or errored. Stop; do not launch an uncontained sandbox. This is a runtime check, not a code read (verify-runtime-state) — do not skip it.
+
+## Step 4 — Launch the hookless session
+
+Run `scripts/launch_sandbox.py --worktree <worktree_path> --settings <settings path> --task-file <task file>`.
+
+It starts a headless `claude -p --bare --dangerously-skip-permissions --settings <settings path>` session in the worktree, so every standards gate is skipped and the two safety gates from the settings file are the only containment. Write the proof-of-concept task to the task file first; the sandbox agent cannot invoke other skills, so the task must be self-contained.
+
+## Step 5 — Judge the result
+
+Read what the sandbox built and decide whether the proof-of-concept proves the idea. On success, move to `promotion.md`. To discard, remove the worktree with `git worktree remove --force <worktree_path>`.

package/skills/release-notes-html/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: release-notes-html
+description: Build a polished self-contained HTML product launch and release-notes page from work completed in the current session, using available repository state, source-of-truth files, tests, approvals, artifacts, commits, pull requests, previews, and release evidence. Use when the user asks to build release notes, create a launch page, document completed work, produce feature-release HTML, or turn the session into product-facing release notes.
+when_to_use: Invoke for requests such as "build release notes for the work you've done," "create release notes HTML," "make a product launch page," "document this completed feature," or "turn our work into a polished release page."
+disable-model-invocation: false
+user-invocable: true
+---
+
+Build a polished, self-contained HTML product launch and release-notes page for the work completed in this session.
+
+Use the current conversation, task history, repository state, completed changes, test results, approvals, generated artifacts, plans, handoffs, file paths, commits, pull requests, and other evidence already available in the session as the source of truth.
+
+Recover the feature name, purpose, capabilities, specifications, usage instructions, validation results, release status, and first production use directly from the available context. Inspect relevant files and repository artifacts when access is available.
+
+Ask one concise clarification question only when the session does not contain enough information to identify the completed feature or its supporting evidence.
+
+## Execution
+
+Act as the orchestrator.
+
+Create a task ledger covering:
+
+- Evidence collection
+- Feature and release-state synthesis
+- Page structure
+- HTML creation
+- Evidence audit
+- Visual and browser review
+- Final delivery
+
+Assign file inspection and HTML creation to executor workers when worker tools are available. The orchestrator owns the structure, factual acceptance, and final audit.
+
+## Evidence rules
+
+Use only facts supported by:
+
+- The current conversation
+- Current session tasks and results
+- Repository files and git state
+- Named source-of-truth files
+- Generated reports, ledgers, plans, and acceptance packets
+- Explicit user approvals
+- Test and CI output already available
+- Pull request and commit data available to the session
+
+Locate the strongest source for each claim.
+
+Preserve exact:
+
+- Feature and package names
+- File paths
+- Commands
+- Dimensions
+- Flags
+- Identifiers
+- JSON keys
+- Test totals
+- Pull request numbers
+- Branch and release status
+
+Place exact technical values inside `<code>` elements.
+
+Include previews, approval claims, test counts, merged status, and production-use claims when the available evidence supports them.
+
+## Page content
+
+Produce one cohesive launch page with a clear hierarchy that a non-engineer can skim.
+
+Include the sections that the completed work supports:
+
+1. Hero with the feature name and primary benefit
+2. A brief explanation of what the feature enables
+3. Major capability highlights
+4. How to run or use it
+5. Exact specifications
+6. Quality, validation, and safety coverage
+7. First production use, debut project, or approved example
+8. Current availability or completion status
+
+Adapt the section names and structure to the actual project. Give every heading a useful takeaway.
+
+## Tone
+
+Write the page as the launch of a completed new capability.
+
+Use present-state product copy focused on:
+
+- What it is
+- What the user can accomplish
+- How it works
+- How to use it
+- What guarantees or validations it provides
+- Where it has already been applied
+
+Keep implementation history, discarded approaches, debugging chronology, and internal justification outside the page unless they are essential to using the feature.
+
+## Voice rules
+
+The reader primarily absorbs headings, bolded leads, and the first sentence of each block.
+
+1. Every title states a plain-language claim.
+2. Each sentence carries one idea.
+3. Lead with reader meaning, then explain the mechanism.
+4. Explain specialized terms at first use.
+5. Keep exact technical values verbatim inside `<code>` elements.
+6. Limit cards to two sentences.
+7. Limit list items to three sentences.
+8. Give each section a one-sentence subtitle that adds information.
+9. Make the complete story understandable from headings and bolded leads alone.
+10. Use concise, active sentences.
+11. Use present-state language throughout.
+12. Give every important fact one clear location.
+
+## Design
+
+Create one valid HTML file with self-contained CSS. CDN-hosted fonts are acceptable.
+
+Use:
+
+- Strong visual hierarchy
+- Spacious typography
+- Scannable cards and sections
+- Responsive desktop and narrow-screen layouts
+- Accessible contrast
+- Clear treatment of code, specifications, and commands
+- An inviting product-launch presentation rather than dense documentation
+
+Use an approved preview or product image when one is already available and supported by the session.
+
+## Output location
+
+Choose the output location from an explicit path already stated in the session.
+
+When no output path has been established, write the file beside the project’s existing results, release, report, or acceptance artifacts using a clear name such as:
+
+`RELEASE_NOTES.html`
+
+Use the operating-system temporary directory only when no project location can be determined safely.
+
+Write the file atomically and create its parent directory when required.
+
+## Acceptance audit
+
+Before delivery:
+
+- Verify every factual claim against the available evidence.
+- Review every heading for a clear takeaway.
+- Review every sentence for one idea.
+- Confirm specialized terms receive plain explanations.
+- Confirm exact technical values remain verbatim.
+- Confirm headings and bolded leads communicate the whole story.
+- Confirm the page is readable at desktop and narrow browser widths.
+- Confirm the output is one complete, valid HTML file.
+- Open the completed page in Chrome or the available default browser when the environment supports it.
+- Correct every issue found during the audit.
+
+## Delivery
+
+Reply with:
+
+1. The full absolute path to the HTML file.
+2. One sentence describing what the release-notes page covers.
+
+Stop after delivering the completed page.

package/skills/skill-builder/CLAUDE.md

@@ -1,12 +1,12 @@
 # skill-builder
 
-Orchestrates the skill-building lifecycle: classify type, scaffold folders, write via `skill-writer`, enforce modularity (sub-skills / composition), write description as a trigger catalog, require deterministic steps as code, self-audit, and refine from real usage.
+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, use `/skill-writer` directly. This skill classifies, scaffolds, gathers context (composition plan, description triggers, deterministic inventory), delegates writing, and self-audits.
+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
 
@@ -45,5 +45,5 @@ Enforces craft standards for new and existing skills. For quick one-off SKILL.md
 
 - 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; `skill-writer` authors. Handoff packet must include type, gap analysis, composition plan, description trigger catalog, deterministic inventory, degree-of-freedom assessment, and constraints.
+- `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/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: skill-builder
 description: >-
-  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose
+  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose
   sub-skills, polish description triggers, enforce deterministic scripts. Triggers:
   build a skill, new skill workflow, improve this skill, optimize skill description,
   skill development lifecycle, skill modularity, skill composition, description
@@ -28,9 +28,9 @@ Highest-signal content. Append a bullet each time a skill build fails in a new w
 
 ## When this skill applies
 
-Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to `/skill-writer`, and self-audits the result.
+Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to the `skill-writer-agent` agent, and self-audits the result.
 
-For quick skill syntax questions or one-off SKILL.md edits, use `/skill-writer` directly instead.
+For quick skill syntax questions or one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly.
 
 **Refusal cases — first match wins:**
 
@@ -161,9 +161,9 @@ Also: story-form descriptions; monolith multi-capability skills; silent reimplem
 
 After every build, improvement, or polish pass, load `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`, **register every bullet as a session task**, and complete each with evidence. Every item must pass before delivery. Fix failures, then re-audit.
 
-## Delegation to skill-writer
+## Delegation to skill-writer-agent
 
-skill-builder orchestrates; skill-writer authors. The handoff packet from Step 4 must include:
+skill-builder orchestrates; the `skill-writer-agent` agent authors. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff packet from Step 4 must include:
 
 - Skill type and folder structure
 - Gap analysis or observation findings (composition plan + description triggers + deterministic inventory)

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

@@ -12,7 +12,7 @@ Best-practice specifications and the mandatory self-audit checklist for the `/sk
 | `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. |
+| `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

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

@@ -1,10 +1,10 @@
 # Delegation Map
 
-How skill-builder delegates work to subagents and `/skill-writer`.
+How skill-builder delegates authoring to the `skill-writer-agent` agent.
 
-## Delegating to skill-writer (Step 4)
+## Delegating to skill-writer-agent (Step 4)
 
-skill-builder orchestrates; skill-writer authors the SKILL.md and companion files. The handoff must be structured so skill-writer has everything it needs.
+skill-builder orchestrates; the `skill-writer-agent` agent authors the SKILL.md and companion files. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff must be structured so the agent has everything it needs.
 
 ### New skill handoff
 

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

@@ -44,7 +44,7 @@ description: >-
 
 ```yaml
 description: >-
-  Skill lifecycle: classify, scaffold, write via skill-writer, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
+  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose sub-skills, polish description triggers. Triggers: build a skill, new skill workflow, improve this skill, optimize skill description, skill development lifecycle, skill modularity.
 ```
 
 ```yaml

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

@@ -54,7 +54,7 @@ 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`.
+The orchestrator owns sequence and gates. Sub-skills own domain detail. skill-builder itself follows this shape: it orchestrates and delegates writing to the `skill-writer-agent` agent (spawned via the Agent tool).
 
 ### Within-skill vs split
 
@@ -85,12 +85,11 @@ In Process or a dedicated **Sub-skills** section:
 | 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.
+Self-audit requires this table (or equivalent) whenever the skill composes others. skill-builder itself delegates SKILL.md authoring to the `skill-writer-agent` agent, spawned via the Agent tool.
 
 ## Anti-patterns
 

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

@@ -6,7 +6,7 @@ Step-by-step workflow files for each skill lifecycle phase, loaded on demand by
 
 | File | Purpose |
 |---|---|
-| `new-skill.md` | Full lifecycle: classify, scaffold, gather (composition + description triggers + deterministic inventory), write via skill-writer, self-audit, deliver. |
+| `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. |
 

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

@@ -83,7 +83,7 @@ For each diagnosis from Step 2:
 6. For checkbox/tracker failures: replace markdown `- [ ]` boards with a plain task-seed list and a seed instruction (`TaskCreate` / `TodoWrite`).
 7. 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.
+Spawn the `skill-writer-agent` agent for larger rewrites, using the refine-skill handoff from delegation-map.md.
 
 **Output:** Modified skill files with targeted fixes.
 

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

@@ -125,11 +125,11 @@ Register each task seed under **Required task seeds** in `deterministic-elements
 
 **Goal:** Produce the skill package — SKILL.md and companion files.
 
-Delegate to `/skill-writer` using the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
+Spawn the `skill-writer-agent` agent (`Agent(subagent_type="skill-writer-agent", ...)`) with the structured handoff from `${CLAUDE_SKILL_DIR}/references/delegation-map.md`.
 
 The handoff must include: skill type, folder structure, gap analysis (composition plan + description triggers + deterministic inventory), initial gotchas, degree of freedom, constraints, sub-skills to name in SKILL.md, exact description string to put in frontmatter, script/test paths for every deterministic step.
 
-After skill-writer produces the draft:
+After the `skill-writer-agent` agent produces the draft:
 
 1. Verify it follows the hub layout (principle → gotchas → when-applies → process → file index → folder map).
 2. Verify SKILL.md body is under 500 lines.