aiblueprint-cli 1.4.108 → 1.4.109

package/agents-config/skills/rules-manager/SKILL.md

@@ -1,204 +1,23 @@
 ---
 name: rules-manager
-description: Create, edit, and maintain AGENTS.md and .agents/rules/ — tech stack, commands, universal rules, rule index, and rule files. Use to add, modify, restructure, or optimize project rules, conventions, and constraints.
+description: Create, edit, and maintain AGENTS.md and .agents/rules/. Use when adding, modifying, restructuring, or optimizing project rules, conventions, or constraints.
 argument-hint: "[init | add <rule-name> | edit | optimize | task description]"
+disable-model-invocation: true
+user-invocable: true
 ---
 
-<core_principle>
-Rules consume tokens on every agent run. Keep them minimal, specific, and discoverable.
+Manage the two-tier rule system: the always-loaded index plus modular files. Every modular file must be linked from the index or agents will not find it.
 
-**Two-tier system:**
+Open [agents-vs-claude.md](references/agents-vs-claude.md) before choosing `AGENTS.md` + `.agents/rules/` versus `CLAUDE.md` + `.claude/rules/`, path-scoped `paths:` frontmatter, or dual-format setup. Run the same workflows against the chosen pair. Open [examples.md](references/examples.md) before writing a new rule file or index skeleton.
 
-- **AGENTS.md** — Always loaded. Acts as the **index** + universal rules.
-- **.agents/rules/\*.md** — Modular rule files for focused topics (changelog, testing, deployment, etc.).
+Never overwrite existing files without asking. Never write a rule file without confirming its content. Default new rules to a modular file (20–60 lines); put 1–2 line constraints in Universal Rules. When the user names index content (stack, commands, universal rules), edit that file in place. Write specific prohibitions. Do not add generic best practices, linter-enforced rules, or facts the agent can read from the code.
 
-**CRITICAL invariant:** Every file in `.agents/rules/` must be referenced in AGENTS.md so agents know it exists. AGENTS.md without a reference = orphaned rule = invisible to agents.
-</core_principle>
+`init`: read package manifests; if the index or rules directory exists, ask before writing; create a <40-line index with an empty Rules section and the rules directory.
 
-<file_layout>
+`add <name>`: slugify the name; `init` if no index; ask what it enforces and when it applies; write the modular file; add one index bullet whose path matches the file.
 
-```
-project-root/
-├── AGENTS.md                  # Index + universal rules (always loaded)
-└── .agents/
-    └── rules/
-        ├── changelog.md       # Rule for changelog management
-        ├── testing.md         # Rule for tests
-        └── deployment.md      # Rule for deployment
-```
+`edit`: change only the named index section; keep every modular-file link intact.
 
-**AGENTS.md must contain a `## Rules` section listing each `.agents/rules/*.md` file with a one-line description.**
-</file_layout>
+`optimize`: inventory index vs files (flag orphans and broken links); strip linter-enforced, generic, verbose, and code-derivable rules; compress to bullets; show the diff and wait. Targets: index <80 lines, each rule <60.
 
-<agents_md_template>
-Minimal AGENTS.md with rules index:
-
-```markdown
-# Project Name
-
-Short description (1-2 lines).
-
-## Tech Stack
-
-- [Non-obvious tech only]
-
-## Commands
-
-- `[dev]` - Dev server
-- `[test]` - Run tests
-
-## Rules
-
-The detailed rules live in `.agents/rules/`. Read the relevant file before acting:
-
-- **Changelog** - [.agents/rules/changelog.md](.agents/rules/changelog.md) - When/how to update CHANGELOG.md
-- **Testing** - [.agents/rules/testing.md](.agents/rules/testing.md) - Test conventions and coverage
-- **Deployment** - [.agents/rules/deployment.md](.agents/rules/deployment.md) - Deploy checklist
-
-## Universal Rules
-
-- [2-3 critical rules that apply everywhere]
-```
-
-The `## Rules` section is the index. Each bullet = one file in `.agents/rules/`. The `## Universal Rules` section holds short, project-wide constraints that don't deserve their own file.
-</agents_md_template>
-
-<rule_file_template>
-Each `.agents/rules/<name>.md` should be focused, short, and actionable.
-
-```markdown
-# [Rule Title]
-
-Short purpose statement (1 line).
-
-## When this applies
-
-- [Specific triggers - what task/context loads this rule]
-
-## Rules
-
-- [Specific, actionable rule]
-- [Another rule with example if format matters]
-
-## Example
-
-[3-5 line concrete example, only if needed]
-```
-
-**Size target:** 20-60 lines per rule file. If longer, split into multiple files.
-</rule_file_template>
-
-<writing_rules>
-**Be specific, never vague:**
-
-```
-NO: "Update changelog properly"
-YES: "Append entry to CHANGELOG.md under ## Unreleased before every PR. Format: - [type] description (#PR)"
-```
-
-**Prohibitions beat positive guidance:**
-
-```
-NO: "Try to write tests"
-YES: "NEVER merge without a passing test for the changed behavior"
-```
-
-**Emphasis hierarchy:** CRITICAL > NEVER > ALWAYS > IMPORTANT
-
-- Lead each section with the most critical rule
-- Use **bold + keyword** for non-negotiables: `**CRITICAL**: Never commit secrets`
-
-**Do NOT include:**
-
-- Generic best practices ("write clean code", "DRY", "SOLID")
-- Linter-enforced rules (ESLint, Prettier, Biome already do this)
-- Things the agent discovers from the code (file structure, framework defaults)
-- Marketing or vision statements
-- Verbose paragraphs - one line is almost always enough
-  </writing_rules>
-
-<workflows>
-
-## `/rules-manager init` - Bootstrap AGENTS.md + .agents/rules/
-
-When the argument contains `init`:
-
-1. **Detect project context** - Read `package.json` or equivalent for name, stack, scripts.
-2. **Check existing files** - If `AGENTS.md` or `.agents/rules/` already exists, read them and ASK before overwriting.
-3. **Create skeleton** - Write AGENTS.md with empty `## Rules` index, ready to populate.
-4. **Create `.agents/rules/` directory** - Empty for now. New rules added via `add` workflow.
-
-Target AGENTS.md size at init: under 40 lines.
-
-## `/rules-manager add <name>` - Add a new rule
-
-When the argument starts with `add`:
-
-1. **Confirm name** - Slugify (e.g., "changelog management" -> `changelog`). Ask user if unclear.
-2. **Read existing AGENTS.md** - Confirm it exists. If not, run `init` first.
-3. **Ask the user for rule content** - What does the rule enforce? When does it apply? Any examples?
-4. **Write `.agents/rules/<name>.md`** - Use the rule file template. Keep it 20-60 lines.
-5. **Update AGENTS.md `## Rules` section** - Add a one-line bullet pointing to the new file:
-   ```
-   - **<Title>** - [.agents/rules/<name>.md](.agents/rules/<name>.md) - <one-line purpose>
-   ```
-6. **Verify the link** - Make sure the path in AGENTS.md exactly matches the created file.
-
-**CRITICAL:** Step 5 is non-negotiable. A rule file without an index entry is invisible.
-
-## `/rules-manager edit` - Modify AGENTS.md directly
-
-When the user wants to change AGENTS.md itself rather than add a rule file — update the tech stack, commands, universal rules, project description, or restructure sections:
-
-1. **Read AGENTS.md** - Load current content.
-2. **Make the targeted edit in place** - Change only the relevant section; leave unrelated sections untouched.
-3. **Preserve the index** - If touching `## Rules`, keep every `.agents/rules/*.md` link intact.
-4. **Stay minimal** - Apply `<writing_rules>`: specific, prohibitions over guidance, no bloat.
-
-This is the default when the user references AGENTS.md content (not a rule file) — e.g. "add a command to AGENTS.md", "update the tech stack", "tighten the universal rules".
-
-## `/rules-manager optimize` - Audit and clean up
-
-When the argument contains `optimize`:
-
-1. **Inventory** - List AGENTS.md and every file in `.agents/rules/`.
-2. **Check the index** - For each file in `.agents/rules/`, verify there's a matching bullet in AGENTS.md `## Rules`. Flag missing entries.
-3. **Check for orphans** - For each AGENTS.md bullet, verify the file exists. Flag broken links.
-4. **Apply bloat removal** - For each rule file, remove:
-   - Linter-enforced rules
-   - Generic best practices
-   - Verbose explanations (compress to one line)
-   - Things derivable from code
-5. **Compress** - Paragraphs to bullets, multi-line rules to single lines.
-6. **Show diff and ask before applying.**
-
-Target sizes:
-
-- AGENTS.md: under 80 lines
-- Each rule file: under 60 lines
-
-## Default - Add a rule based on description
-
-When the argument is a free-form task (e.g., "add a rule about how we tag releases"):
-
-1. Treat as `add` with auto-derived name.
-2. Ask the user 1-2 clarifying questions if the rule scope is unclear.
-3. Follow the `add` workflow.
-   </workflows>
-
-<rules_for_this_skill>
-
-- This skill manages ALL of AGENTS.md (tech stack, commands, universal rules, index, description) and `.agents/rules/` — not just creating new rule files. Editing existing AGENTS.md content is fully in scope.
-- ALWAYS update AGENTS.md `## Rules` index when creating a file in `.agents/rules/`
-- NEVER create a rule file without confirming with the user what it should contain
-- NEVER overwrite existing AGENTS.md or rule files without asking
-- Default to short rule files (20-60 lines). Split if larger.
-- When user asks "create a rule", default to creating a file in `.agents/rules/` (not inline in AGENTS.md), unless the rule is 1-2 lines and fits the universal section.
-- When the user references AGENTS.md content directly (a command, the stack, a universal rule), edit AGENTS.md in place via the `edit` workflow — don't spin up a new rule file.
-  </rules_for_this_skill>
-
-<reference_guides>
-
-- **Examples**: [references/examples.md](references/examples.md) - Sample rule files (changelog, testing, deployment)
-- **AGENTS.md vs CLAUDE.md**: [references/agents-vs-claude.md](references/agents-vs-claude.md) - When to use which format
-  </reference_guides>
+A free-form request is `add` with a derived name. Ask 1–2 scope questions if the rule is unclear.

package/agents-config/skills/skill-manager/SKILL.md

@@ -1,171 +1,32 @@
 ---
 name: skill-manager
-description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, prompts, frontmatter, references, scripts, discovery, and predictable skill design.
+description: Create, edit, audit, or prune Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and skill discovery.
 ---
 
-# Skill Manager
+Write skills the way `$analyze`, `$plan`, `$implement`, `$code-review`, and `$verify` are written.
 
-Authoring guide for skills/rules across three agent platforms. All three share the same idea: a small markdown file with frontmatter, optional references, optional scripts. The discovery rules and frontmatter fields differ.
+## Target
 
-| Platform     | File                                          | Frontmatter fields                                       | Optional config              |
-| :----------- | :-------------------------------------------- | :------------------------------------------------------- | :--------------------------- |
-| Claude Code  | `<scope>/skills/<name>/SKILL.md`              | `name`, `description`, plus invocation/execution fields  | -                            |
-| Codex        | `<scope>/.agents/skills/<name>/SKILL.md`      | `name`, `description`                                    | `agents/openai.yaml`         |
-| Cursor       | `.cursor/rules/<name>.md` or `.mdc`           | `description`, `globs`, `alwaysApply`                    | `AGENTS.md` (no frontmatter) |
+- One job. Imperative. Every line changes behavior.
+- Body under ~40 lines unless the job is genuinely multi-branch.
+- Description 50–300 chars: capability first, then `Use when` + trigger words.
+- No README, changelog, or theory. No restating model defaults.
+- References only for platform or schema detail the body cannot hold. Name the file and when to open it.
+- User-only workflows: `disable-model-invocation: true`.
 
-Pick the platform first, then read the matching reference file:
+## Write
 
-- Claude Code → see [references/claude-code.md](references/claude-code.md)
-- Codex      → see [references/codex.md](references/codex.md)
-- Cursor     → see [references/cursor.md](references/cursor.md)
-- Description quality → see [references/description-recommandation.md](references/description-recommandation.md)
-- Skill-writing vocabulary → see [references/skill-writing-glossary.md](references/skill-writing-glossary.md)
+1. Confirm 2–3 trigger prompts with the user.
+2. Pick the platform. Default from the path: `.claude` → Claude, `.agents` → Codex, `.cursor` → Cursor. Ask if unclear.
+3. Write frontmatter, then the body: inspect → act → return → stop.
+4. Run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root.
 
-If unsure which the user wants, ask. Default to Claude Code when working under `~/.claude/` or `.claude/`, Codex when under `~/.agents/` or `.agents/`, Cursor when under `.cursor/`.
+Personal skills live in `~/.agents/skills/<name>/`. Platform layout and frontmatter: [claude-code.md](references/claude-code.md), [codex.md](references/codex.md), [cursor.md](references/cursor.md). Description rules: [description-recommandation.md](references/description-recommandation.md).
 
-## Core principles (all platforms)
+## Audit
 
-### Optimize for predictability
+For each line: would removing it change behavior? Delete no-ops, duplicates, and stale rules. State the positive target; keep prohibitions only as hard guardrails.
 
-A skill should make the agent follow the same process on repeated runs, even when the outputs differ. Treat predictability as the root quality; token cost and maintainability improve when the process is explicit and lean.
+Online research: `$find-docs` for current technical docs; `$exa-search` for broader web research.
 
-### Concise is key
-
-The context window is shared with the system prompt, conversation, other skills' metadata, and the user request. Only add context the agent doesn't already have. Challenge each line: does it justify its tokens?
-
-### Match freedom to fragility
-
-- **High freedom** (prose instructions): multiple valid approaches, decisions depend on context.
-- **Medium freedom** (pseudocode, scripts with parameters): preferred pattern exists, some variation OK.
-- **Low freedom** (specific scripts, few parameters): fragile, error-prone, must run a fixed sequence.
-
-### Progressive disclosure
-
-Three loading levels:
-
-1. **Metadata** (name + description): always in context. Keep tight.
-2. **SKILL.md body**: loaded when the skill triggers. Aim under ~500 lines.
-3. **References**: loaded on demand. Move variant-specific detail, schemas, and long examples here.
-
-Keep references one level deep. Reference them by name in SKILL.md so the agent knows when to open them.
-
-### Design the information hierarchy
-
-Put ordered actions in steps and definitions or rules in reference sections. End important steps with a checkable completion criterion; vague criteria invite premature completion. Inline what every execution branch needs and move branch-specific material behind a context pointer whose wording says when to load it.
-
-Split a skill only when the split earns its cost:
-
-- **By invocation:** a distinct leading word must trigger the new skill independently.
-- **By sequence:** hiding later steps prevents the agent from rushing the current step.
-
-Every model-invoked skill spends context load through its description. Every user-only skill spends human cognitive load because the user must remember it. When user-only skills become hard to remember, add one router instead of making every skill model-invoked.
-
-### Use leading words
-
-A leading word is a compact pretrained concept such as `tight loop`, `tracer bullet`, or `handoff`. Reuse the same term in the description and body so it anchors both invocation and execution. Prefer one strong term over repeated prose that restates the same behavior.
-
-### Prune aggressively
-
-Keep each meaning in one authoritative place. Audit every sentence with the no-op test: would removing it change agent behavior? Delete no-ops instead of polishing them. Watch for:
-
-- **Duplication:** the same rule appears in several places.
-- **Sediment:** stale instructions remain because removal feels risky.
-- **Sprawl:** every line may be relevant, but the active path carries too much context.
-- **Negation:** naming forbidden behavior makes it more available; state the positive target and reserve prohibitions for hard guardrails.
-- **Negative space:** omitted decisions silently fall back to model priors; decide whether each omission is intentional.
-- **Premature completion:** sharpen the completion criterion before splitting the sequence.
-
-### Online research routing
-
-When a skill or agent needs online research, name the exact research skill to use instead of relying on vague web-search language:
-
-- Use `~/.agents/skills/find-docs/SKILL.md` for current technical documentation, API references, config options, SDKs, CLIs, cloud services, and code examples.
-- Use `~/.agents/skills/exa-search/SKILL.md` for broader online research, recent information, source discovery, similar pages, URL extraction, or cited web answers.
-- Mention default harness tools for local code, file, git, shell, and browser inspection.
-- Keep built-in `WebSearch` and `WebFetch` as fallback tools unless the user explicitly asks for them.
-- For restricted agents, include `Skill` and `Bash` in the tool list when these skills need to run local CLIs.
-- Never put secrets, tokens, credentials, personal data, or proprietary code in external queries.
-
-### Skill anatomy
-
-```
-skill-name/
-├── SKILL.md            # required: frontmatter + instructions
-├── references/         # optional: docs loaded on demand
-├── scripts/            # optional: deterministic code
-└── assets/             # optional: templates/icons used in output
-```
-
-Do NOT add README, CHANGELOG, INSTALLATION_GUIDE, etc. Only files the agent needs at runtime.
-
-## Authoring workflow
-
-1. **Pin down the use case.** Get 2-3 concrete example prompts that should trigger the skill. Confirm with the user.
-2. **List reusable parts.** What scripts, references, or assets recur? Add only those.
-3. **Write SKILL.md.** Frontmatter first (description is what triggers it - front-load keywords). Then imperative-form body.
-4. **Test the description.** The description has to read like a trigger phrase, not a label. Examples in each reference file.
-5. **Iterate after real use.** Note what the agent got wrong; refine the relevant section.
-
-## Writing the description
-
-The `description` field is the single most important line in the file - it's what the model uses to decide to load the skill. This is a hard rule: descriptions must be between 50 and 300 characters.
-
-Write it as:
-
-- Front-load trigger words ("Use when...", "create a skill", "review a PR").
-- State scope and boundaries explicitly.
-- Mention concrete file names or commands the user might type.
-- Keep it short enough to stay under 300 characters, while still specific enough to trigger reliably.
-
-Bad: `"Helper for skills."`
-Good: `"Create and edit skills/rules across Claude Code, OpenAI Codex, and Cursor. Use when the user asks to 'create a skill'..."`
-
-To validate skill descriptions, frontmatter fields, `agents/openai.yaml`, and skill directory shape, run:
-
-```bash
-bun scripts/inspect-description.ts
-```
-
-By default, this checks `~/.agents/skills` only and follows symlinked skill directories inside that root. Pass one or more roots to inspect a different set. Passing a `.cursor/rules` directory validates Cursor rule frontmatter too:
-
-```bash
-bun scripts/inspect-description.ts .agents/skills
-```
-
-For researched guidance and examples, see [references/description-recommandation.md](references/description-recommandation.md).
-
-## Where each platform stores skills
-
-**Canonical personal skills:** `~/.agents/skills/` is the single source of truth (git repo `Melvynx/agents-config`). It is an official user-level root for both Cursor and Codex, so they read it directly. Write new personal skills only under `~/.agents/skills/<name>/`.
-
-### Codex profile activity icons
-
-Codex's Profile activity view does not resolve standalone skill icons from `agents/openai.yaml`. It resolves known built-in skill icons or the logo of a matching installed plugin. After creating, renaming, or changing the icon metadata of a personal skill, sync the identity-only personal plugin wrappers:
-
-```bash
-bun ~/.agents/scripts/sync-codex-profile-icons.ts --install
-bun ~/.agents/scripts/audit-codex-profile-icons.ts
-```
-
-The wrappers intentionally contain no executable skills, so they provide `logo` / `logoDark` metadata without duplicating skill discovery. Keep `~/plugins` linked to `~/.agents/plugins/plugins`; the sync script creates the link when absent.
-
-Per the official Cursor docs ([cursor.com/docs/skills](https://cursor.com/docs/skills)), user-level roots are `~/.agents/skills/` and `~/.cursor/skills/`, plus compat dirs `~/.claude/skills/` and `~/.codex/skills/`. `~/.cursor/skills-cursor/` is NOT a documented path; do not use it.
-
-Because `~/.agents/skills/` is read directly, the only symlinks needed are the compat dirs for agents that do not read `~/.agents/skills/` themselves:
-
-```bash
-~/.claude/skills -> ~/.agents/skills   # Claude Code reads ~/.claude/skills
-~/.codex/skills  -> ~/.agents/skills   # Codex compat (optional; Codex also reads ~/.agents/skills)
-```
-
-Do NOT symlink `~/.cursor/skills` or `~/.cursor/skills-cursor` to `~/.agents/skills/`; that makes Cursor scan the same skills two or three times. To repair the compat symlinks if missing:
-
-```bash
-ln -s ~/.agents/skills ~/.claude/skills
-```
-
-See the per-platform reference files. Quick reminders:
-
-- **Cursor**: reads `~/.agents/skills/` and `~/.cursor/skills/` (user-level), `.agents/skills/` and `.cursor/skills/` (project). Use `~/.agents/skills/` as the single root; skip the `~/.cursor/skills*` symlinks.
-- **Claude Code**: `~/.claude/skills/` (symlink → `~/.agents/skills/`) or `.claude/skills/` (project). Higher scope wins on name collision.
-- **Codex**: `.agents/skills/` walks up from CWD to repo root, then `~/.agents/skills/`, then `/etc/codex/skills`, then system bundled.
+After creating or renaming a personal skill icon, run `bun ~/.agents/scripts/sync-codex-profile-icons.ts --install`. Compat: `~/.claude/skills` and `~/.codex/skills` symlink to `~/.agents/skills`. Do not symlink `~/.cursor/skills`.

package/agents-config/skills/skill-manager/references/description-recommandation.md

@@ -1,97 +1,27 @@
-# Description Recommendations
+# Description
 
-Use this when writing or refining the `description` field for Claude Code skills, OpenAI Codex skills, or Cursor intelligent rules.
+Load this when writing or refining a `description` field.
 
-## Sources
+Official docs: Codex https://developers.openai.com/codex/skills · Claude https://docs.anthropic.com/en/docs/claude-code/skills · Cursor https://cursor.com/docs/skills
 
-- OpenAI Codex Agent Skills: https://developers.openai.com/codex/skills
-- Anthropic Agent Skills best practices: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/best-practices
-- Anthropic Agent Skills overview: https://console.anthropic.com/docs/en/agents-and-tools/agent-skills/overview
-- Claude Code skills docs: https://docs.anthropic.com/en/docs/claude-code/skills
-- Cursor rules docs: https://cursor.com/help/customization/rules
+## Rules
 
-## Hard Rules
+- 50–300 characters.
+- First clause useful alone; skill lists may truncate.
+- What it does + when to use it. Third person. No `I can` / `You can`.
+- No XML, tables, long examples, or body-level steps.
+- Trigger-first: nouns, verbs, file names, and commands the user would type.
 
-- Keep every description between 50 and 300 characters.
-- Make the first clause useful on its own; skill lists may shorten descriptions.
-- Include both what the skill does and when it should be used.
-- Use third person. Do not write "I can..." or "You can...".
-- Do not include XML tags, markdown tables, long examples, or implementation steps.
-- Do not duplicate the full SKILL.md body. The description is only discovery metadata.
-
-## What Good Descriptions Do
-
-A good description helps the model decide whether to load the skill before it has read the skill body. It should answer three questions:
-
-1. What capability does this skill provide?
-2. Which user requests, file names, commands, or domain terms should trigger it?
-3. What boundary keeps it from triggering on adjacent but wrong tasks?
-
-Prefer concrete nouns, verbs, and file names over generic labels. Use terms a user would actually type: `SKILL.md`, `.cursor/rules`, `commit message`, `invoice`, `wrangler`, `Netlify deploy`, `DOCX`, `.xlsx`.
-
-## Recommended Shape
-
-Use one or two compact sentences:
-
-```yaml
-description: <Primary capability>. Use when <trigger phrases, file types, commands, or task context>.
-```
-
-For reference-only skills:
-
-```yaml
-description: <Domain conventions or reference material>. Use when working on <specific files, modules, APIs, or workflows>.
-```
-
-For side-effecting workflows, be narrower:
-
-```yaml
-description: Prepare and verify production deploys. Use only when the user explicitly asks to deploy, release, publish, or check deployment status.
-```
-
-## Examples
-
-Good:
-
-```yaml
-description: Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.
-```
-
-Good:
-
-```yaml
-description: Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.
-```
-
-Too vague:
+## Shape
 
 ```yaml
-description: Helps with skills.
+description: <Primary capability>. Use when <trigger phrases, files, commands, or task context>.
 ```
 
-Too broad:
+Good: `Create or edit Claude, Codex, and Cursor skills/rules. Use for SKILL.md, .cursor/rules, AGENTS.md, frontmatter, references, scripts, and discovery rules.`
 
-```yaml
-description: Manage all developer workflow tasks, docs, rules, automation, repository work, deployment, testing, and issue handling.
-```
-
-Wrong point of view:
+Good: `Review GitHub pull request feedback and implement requested changes. Use when the user asks to address PR comments, review threads, or requested changes.`
 
-```yaml
-description: I can help you write better skill descriptions.
-```
+Bad: `Helps with skills.` / `I can help you write better skill descriptions.` / a catalog of every adjacent task.
 
-## Checklist
-
-- [ ] 50-300 characters.
-- [ ] First words contain the primary trigger.
-- [ ] Mentions the key files, commands, domains, or user phrases.
-- [ ] Says when to use it, not only what it is.
-- [ ] Specific enough to avoid accidental invocation.
-- [ ] No body-level instructions, setup steps, or long examples.
-
-Run the local inspector after editing:
-
-```bash
-bun scripts/inspect-description.ts
-```
+Then run `bun ~/.agents/skills/skill-manager/scripts/inspect-description.ts` on the skill root.

package/agents-config/skills/test-audit/CAMPAIGN.md

@@ -0,0 +1,117 @@
+# Test-pruning campaign
+
+Campaign mode prunes one subsystem's whole test surface in one PR: a package,
+a plugin, or one core area. The value bar, retention bar, candidate evidence,
+and validation in [SKILL.md](SKILL.md) apply to every lane. This file adds the
+order of work and the lessons of a full campaign, drawn from a campaign on a
+Telegram messaging plugin. Each step ends on its completion criterion; do not
+start the next step early.
+
+## 1. Baseline
+
+Record the subsystem's test and support line counts and every test file's
+pass/fail state at a pinned `main` SHA. Keep baseline failures in their own
+list: in the Telegram campaign, all three were real delivery bugs, not stale
+tests.
+
+Done when every in-scope test file has a recorded baseline result.
+
+## 2. Lanes and inventory
+
+Split the surface into **lanes** along production owner boundaries, not file
+prefixes. For Telegram these were accounts, commands, context, dispatch,
+inbound, outbound, persistence, transport, shared, harness, and live/QA
+scenarios. Include the subsystem's cases at shared core boundaries and its QA
+and live-proof harness tests.
+
+Done when every test file and QA scenario the subsystem owns belongs to exactly
+one lane.
+
+## 3. Read-only ledger per lane
+
+Give each lane to its own read-only agent. The agent reads every assigned test
+in full, including parameter tables. It also reads the production owners and
+their entry points, callers, history, and CI routing. Each test declaration
+goes into a written **ledger** with one mark. An `it.each` is one declaration
+unless its rows need different marks; then mark each row.
+
+- `R`: retain, naming the contract and the bug it catches; a retained test that
+  only moves to a better-named file stays `R` with the move noted;
+- `F`: retain the contract but repair the assertion, such as a vacuous negative
+  that passes when only one of several items is missing;
+- `C`: consolidate, naming the owner that absorbs the assertion first: a sibling
+  table case, a stronger boundary suite, or the shared owner in another package;
+- `D`: delete, naming the proof that remains, or why no contract exists.
+
+Judge a test by its assertions, not its name. One Telegram test named for
+retiring a progress window asserted the window was _not_ cleared.
+
+Done when every declaration in the lane has a mark and an evidence line.
+
+## 4. Layer plan per lane
+
+Treat the per-test ledger as input, not as the edit list. A second read-only
+pass, starting from the ledger, looks for the redundant **layer**. In Telegram,
+several dispatch suites replayed the same shared compositor through one mocked
+preview, around stronger real-stream and HTTP-fixture suites. Name the
+**keeper** suite for each contract. Prefer the real transport boundary with a
+fake network over a mocked collaborator. Correct any ledger errors this pass
+finds.
+
+Done when each lane plan names its retired files, its keeper per contract, the
+assertions to carry into keepers, and the test-only production seams unlocked.
+
+## 5. Cutover
+
+Edit lane by lane. Serialize changes to shared harnesses and support files
+through one owner. With each lane, remove the test-only production seams it
+unlocks: injection parameters, getters, reset exports, and indirection layers.
+Register moved suites in CI routing and test inventories. Update shrink-only
+line-cap baselines. Put durable test-ownership rules in the subsystem's
+`AGENTS.md`, drawn from mistakes this campaign actually found.
+
+Done when every lane plan is applied and each lane's keepers pass.
+
+## 6. Preservation review
+
+Before claiming completion, have independent reviewers compare deleted
+coverage against the keepers, one reviewer per boundary group. They look for
+contracts that lost their only proof. They also look for new assertions that
+cannot fail, such as a rejection row the production code never reaches. The
+Telegram review found nine real gaps and one unreachable assertion.
+
+For each restored contract, make one deliberate **mutation** of the production
+owner and confirm the keeper goes red. Then restore the source byte for byte.
+
+Done when every reported gap is restored or rejected with source evidence, and
+every restored contract has a caught mutation.
+
+## 7. Product defects
+
+A baseline failure that survives into a keeper is a bug report. Fix it at its
+owner as a separate commit, and prove it through the real user flow, with a
+**control** run that reverts the fix and shows the old behavior. Record
+unrelated product discrepancies you find as follow-ups instead of fixing them
+in the campaign.
+
+Done when each repaired defect has a failing control and a passing candidate
+on the same harness.
+
+## 8. Reconcile and hand off
+
+Campaigns outlive many `main` commits. Merge `main` rather than rebasing a
+long, many-commit campaign. When `main` modified a file the campaign
+deleted, keep the deletion. Port the new contract into the keeper instead, and
+confirm every new regression `main` added still has a home. Rerun the whole
+subsystem suite and repeat live proof on the merged head.
+
+Expect review tooling to see a truncated file list on a diff this large.
+Record maintainer decisions for generic compatibility flags in the PR evidence
+rather than editing gates.
+
+Hand off with the [SKILL.md](SKILL.md) report, plus:
+
+- baseline and final test/support line counts, with production counted separately;
+- lanes, retired layers, and keepers;
+- preservation gaps found and their mutations;
+- product defects with control and candidate proof.