From e69b9923c828bad34b0b7b61fb2622b9291b10ca Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 26 May 2026 09:58:55 -0600 Subject: [PATCH 1/4] .claude/rules: replace skill guidance symlinks with index file Replace the 23 one-symlink-per-doc entries under .claude/rules/skills/ with a single .claude/rules/skill-building-guidance.md index file. The index carries paths: "plugin/skills/**/*.md" so it loads only when a skill file is being read, and lists every guidance doc with a 1-3 sentence description so Claude can pick the relevant subset to open on demand instead of loading all 23 docs at once. This mirrors the per-file-type index-file pattern that /coding-standard now uses for coding standards. --- .claude/rules/skill-building-guidance.md | 56 +++++++++++++++++++ .../skills/allowed-tools-AskUserQuestion.md | 1 - .../skills/allowed-tools-bash-permissions.md | 1 - .claude/rules/skills/context-hygiene.md | 1 - .../skills/context-injection-commands.md | 1 - .../cowork-specific-skill-instructions.md | 1 - .../rules/skills/documentation-maintenance.md | 1 - .../rules/skills/dynamic-project-discovery.md | 1 - .claude/rules/skills/graceful-degradation.md | 1 - .../hardening-fuzzy-vs-deterministic.md | 1 - .claude/rules/skills/naming-conventions.md | 1 - .../rules/skills/optional-git-repositories.md | 1 - .../rules/skills/progressive-disclosure.md | 1 - .../skills/script-execution-instructions.md | 1 - .claude/rules/skills/security-restrictions.md | 1 - .claude/rules/skills/skill-composition.md | 1 - .claude/rules/skills/skill-decomposition.md | 1 - .../skills/skill-description-frontmatter.md | 1 - .claude/rules/skills/skill-reference-files.md | 1 - .../skills/success-criteria-and-testing.md | 1 - .claude/rules/skills/troubleshooting.md | 1 - .claude/rules/skills/use-case-planning.md | 1 - .claude/rules/skills/workflow-patterns.md | 1 - .../skills/writing-effective-instructions.md | 1 - 24 files changed, 56 insertions(+), 23 deletions(-) create mode 100644 .claude/rules/skill-building-guidance.md delete mode 120000 .claude/rules/skills/allowed-tools-AskUserQuestion.md delete mode 120000 .claude/rules/skills/allowed-tools-bash-permissions.md delete mode 120000 .claude/rules/skills/context-hygiene.md delete mode 120000 .claude/rules/skills/context-injection-commands.md delete mode 120000 .claude/rules/skills/cowork-specific-skill-instructions.md delete mode 120000 .claude/rules/skills/documentation-maintenance.md delete mode 120000 .claude/rules/skills/dynamic-project-discovery.md delete mode 120000 .claude/rules/skills/graceful-degradation.md delete mode 120000 .claude/rules/skills/hardening-fuzzy-vs-deterministic.md delete mode 120000 .claude/rules/skills/naming-conventions.md delete mode 120000 .claude/rules/skills/optional-git-repositories.md delete mode 120000 .claude/rules/skills/progressive-disclosure.md delete mode 120000 .claude/rules/skills/script-execution-instructions.md delete mode 120000 .claude/rules/skills/security-restrictions.md delete mode 120000 .claude/rules/skills/skill-composition.md delete mode 120000 .claude/rules/skills/skill-decomposition.md delete mode 120000 .claude/rules/skills/skill-description-frontmatter.md delete mode 120000 .claude/rules/skills/skill-reference-files.md delete mode 120000 .claude/rules/skills/success-criteria-and-testing.md delete mode 120000 .claude/rules/skills/troubleshooting.md delete mode 120000 .claude/rules/skills/use-case-planning.md delete mode 120000 .claude/rules/skills/workflow-patterns.md delete mode 120000 .claude/rules/skills/writing-effective-instructions.md diff --git a/.claude/rules/skill-building-guidance.md b/.claude/rules/skill-building-guidance.md new file mode 100644 index 0000000..7a18412 --- /dev/null +++ b/.claude/rules/skill-building-guidance.md @@ -0,0 +1,56 @@ +--- +paths: + - "plugin/skills/**/*.md" + - "plugin/skills/**/scripts/**" +--- + +# Skill-building guidance index + +You are reading this file because Claude Code loaded it as a path-scoped +rule — you just read or are about to read a file under `plugin/skills/`. + +This file is an **index**, not guidance. Each entry below points to a +canonical skill-building guidance document with a short description of +what it covers and when it applies. + +Skill-building guidance lives in `docs/guidance/skill-building-guidance/` +and is exposed to Claude Code through this single index file. The full +text of any individual guidance doc is loaded only when you decide it +applies and use the Read tool to open it. This keeps context lean and +lets you make a relevance decision before paying the token cost. + +**Do not read every linked document.** For the specific task you are +doing right now, scan the descriptions and identify only the documents +that are clearly relevant. Then use the Read tool to open just those +files. If no entry is clearly relevant, do not open any of them. + +If you are unsure whether a guidance doc applies, do not open it. The +author of the work can prompt you to load a specific doc if needed. +Loading guidance that does not apply burns context and dilutes attention +on the parts that do. + +## Available guidance + +- [`AskUserQuestion` in Skill `allowed-tools`](../../docs/guidance/skill-building-guidance/allowed-tools-AskUserQuestion.md) — Why `AskUserQuestion` must never appear in a skill's `allowed-tools` frontmatter. Read when adding or editing the `allowed-tools` line in a SKILL.md. +- [Bash Permission Patterns in `allowed-tools`](../../docs/guidance/skill-building-guidance/allowed-tools-bash-permissions.md) — Syntax and granularity rules for `Bash(...)` entries in `allowed-tools`. Read when adding, removing, or scoping bash commands in a SKILL.md. +- [Context Hygiene](../../docs/guidance/skill-building-guidance/context-hygiene.md) — The attention-budget reasoning behind progressive disclosure, frontmatter conciseness, and reference extraction. Read when deciding whether content earns its place in a SKILL.md or should move to `references/`. +- [Context Injection Commands in Skill Files](../../docs/guidance/skill-building-guidance/context-injection-commands.md) — Using `` !`command` `` syntax to inject runtime context at skill load time. Read when adding or debugging a `## Project Context` block or any inline shell command in a skill. +- [Claude Cowork — Complete Reference](../../docs/guidance/skill-building-guidance/cowork-specific-skill-instructions.md) — Reference for skills targeted at the Claude Cowork desktop product (not developer workflows). Read only when authoring a skill that ships for Cowork users. +- [Documentation Maintenance](../../docs/guidance/skill-building-guidance/documentation-maintenance.md) — Auditing skills so their instructions don't silently rot when the underlying tooling, agents, or repository conventions change. Read when editing a skill that hasn't been touched in a while, or when downstream code has changed shape. +- [Dynamic Project Discovery](../../docs/guidance/skill-building-guidance/dynamic-project-discovery.md) — Rules for discovering branches, tool availability, and project structure at runtime instead of hardcoding. Read when a skill needs to know the default branch, project layout, or which CLIs are installed. +- [Graceful Degradation](../../docs/guidance/skill-building-guidance/graceful-degradation.md) — Detecting partial environments (missing git history, absent project config) and selecting a named execution mode rather than hard-failing. Read when a skill must still produce useful output in incomplete environments. +- [Hardening: Fuzzy vs. Deterministic Steps](../../docs/guidance/skill-building-guidance/hardening-fuzzy-vs-deterministic.md) — Decision framework for classifying steps as fuzzy reasoning (stay in SKILL.md) or deterministic operations (extract to scripts). Read when a SKILL.md has steps that could become flaky or when deciding to add a script. +- [Naming Conventions](../../docs/guidance/skill-building-guidance/naming-conventions.md) — Rules for naming plugins, skills, directories, and the `name` field so users can discover and recognize skills. Read when creating a new skill, renaming an existing one, or changing a plugin directory. +- [Optional Git Repositories](../../docs/guidance/skill-building-guidance/optional-git-repositories.md) — Why analysis skills should treat git as optional and how to detect git state safely. Read when a skill uses any `git` command or assumes a repository, remote, or branch exists. +- [Progressive Disclosure](../../docs/guidance/skill-building-guidance/progressive-disclosure.md) — The three-level architecture (frontmatter, SKILL.md body, `references/`) and rules for what belongs in each level. Read when deciding where new content goes in a skill, or when a SKILL.md is growing too large. +- [Script Execution Instructions in SKILL.md](../../docs/guidance/skill-building-guidance/script-execution-instructions.md) — How to describe script invocations as numbered prose instructions, not fenced code blocks, with explicit `${CLAUDE_SKILL_DIR}` paths. Read when a skill calls a shell script from its steps. +- [Security Restrictions](../../docs/guidance/skill-building-guidance/security-restrictions.md) — Frontmatter restrictions that prevent prompt injection and silent failures, including no XML angle brackets in YAML. Read when editing any field in a skill's YAML frontmatter. +- [Skill Composition](../../docs/guidance/skill-building-guidance/skill-composition.md) — The rule against sub-skill calls (skills invoking other skills via the Skill tool) and what to do instead. Read before reaching for a sub-skill call. +- [Skill Decomposition](../../docs/guidance/skill-building-guidance/skill-decomposition.md) — Single-responsibility rules for skills and how to split a skill that has grown to do too much. Read when a skill's description starts to list multiple unrelated outcomes. +- [Skill Description Frontmatter](../../docs/guidance/skill-building-guidance/skill-description-frontmatter.md) — How the `description` field competes for selection across all loaded skills and how to write descriptions that trigger correctly without false positives. Read when writing or revising a `description:` line. +- [Skill Reference Files](../../docs/guidance/skill-building-guidance/skill-reference-files.md) — How `references/` files work as the third level of progressive disclosure and what content belongs there versus in SKILL.md. Read when extracting templates, checklists, or domain knowledge out of a SKILL.md. +- [Success Criteria and Testing](../../docs/guidance/skill-building-guidance/success-criteria-and-testing.md) — The three test types (triggering, functional, comparative) and how to validate a skill works. Read after building a skill, or when a skill is producing inconsistent results. +- [Troubleshooting](../../docs/guidance/skill-building-guidance/troubleshooting.md) — Common symptoms encountered when building or using skills, organized by failure mode, with the likely cause and fix. Read when a skill won't upload, won't trigger, hangs on a permission prompt, or behaves unexpectedly. +- [Use Case Planning](../../docs/guidance/skill-building-guidance/use-case-planning.md) — The pre-development step of defining 2-3 concrete use cases before writing a SKILL.md. Read when starting a new skill from scratch. +- [Workflow Patterns](../../docs/guidance/skill-building-guidance/workflow-patterns.md) — The four structural patterns that appear across well-built skills and how to compose them within a single SKILL.md. Read when designing or refactoring the step structure of a skill. +- [Writing Effective Instructions](../../docs/guidance/skill-building-guidance/writing-effective-instructions.md) — Rules for writing the SKILL.md body so Claude follows the workflow reliably: specificity, recency, structure, action verbs. Read when the SKILL.md body is being authored or when steps are producing inconsistent results. diff --git a/.claude/rules/skills/allowed-tools-AskUserQuestion.md b/.claude/rules/skills/allowed-tools-AskUserQuestion.md deleted file mode 120000 index c66af66..0000000 --- a/.claude/rules/skills/allowed-tools-AskUserQuestion.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/allowed-tools-AskUserQuestion.md \ No newline at end of file diff --git a/.claude/rules/skills/allowed-tools-bash-permissions.md b/.claude/rules/skills/allowed-tools-bash-permissions.md deleted file mode 120000 index 2f4e55d..0000000 --- a/.claude/rules/skills/allowed-tools-bash-permissions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/allowed-tools-bash-permissions.md \ No newline at end of file diff --git a/.claude/rules/skills/context-hygiene.md b/.claude/rules/skills/context-hygiene.md deleted file mode 120000 index f79f3ac..0000000 --- a/.claude/rules/skills/context-hygiene.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/context-hygiene.md \ No newline at end of file diff --git a/.claude/rules/skills/context-injection-commands.md b/.claude/rules/skills/context-injection-commands.md deleted file mode 120000 index a5d4439..0000000 --- a/.claude/rules/skills/context-injection-commands.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/context-injection-commands.md \ No newline at end of file diff --git a/.claude/rules/skills/cowork-specific-skill-instructions.md b/.claude/rules/skills/cowork-specific-skill-instructions.md deleted file mode 120000 index 6b3fae5..0000000 --- a/.claude/rules/skills/cowork-specific-skill-instructions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/cowork-specific-skill-instructions.md \ No newline at end of file diff --git a/.claude/rules/skills/documentation-maintenance.md b/.claude/rules/skills/documentation-maintenance.md deleted file mode 120000 index 1b95358..0000000 --- a/.claude/rules/skills/documentation-maintenance.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/documentation-maintenance.md \ No newline at end of file diff --git a/.claude/rules/skills/dynamic-project-discovery.md b/.claude/rules/skills/dynamic-project-discovery.md deleted file mode 120000 index e633d6a..0000000 --- a/.claude/rules/skills/dynamic-project-discovery.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/dynamic-project-discovery.md \ No newline at end of file diff --git a/.claude/rules/skills/graceful-degradation.md b/.claude/rules/skills/graceful-degradation.md deleted file mode 120000 index bd48924..0000000 --- a/.claude/rules/skills/graceful-degradation.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/graceful-degradation.md \ No newline at end of file diff --git a/.claude/rules/skills/hardening-fuzzy-vs-deterministic.md b/.claude/rules/skills/hardening-fuzzy-vs-deterministic.md deleted file mode 120000 index 6f98509..0000000 --- a/.claude/rules/skills/hardening-fuzzy-vs-deterministic.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/hardening-fuzzy-vs-deterministic.md \ No newline at end of file diff --git a/.claude/rules/skills/naming-conventions.md b/.claude/rules/skills/naming-conventions.md deleted file mode 120000 index a3a469d..0000000 --- a/.claude/rules/skills/naming-conventions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/naming-conventions.md \ No newline at end of file diff --git a/.claude/rules/skills/optional-git-repositories.md b/.claude/rules/skills/optional-git-repositories.md deleted file mode 120000 index 0f7b2e6..0000000 --- a/.claude/rules/skills/optional-git-repositories.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/optional-git-repositories.md \ No newline at end of file diff --git a/.claude/rules/skills/progressive-disclosure.md b/.claude/rules/skills/progressive-disclosure.md deleted file mode 120000 index 73bb351..0000000 --- a/.claude/rules/skills/progressive-disclosure.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/progressive-disclosure.md \ No newline at end of file diff --git a/.claude/rules/skills/script-execution-instructions.md b/.claude/rules/skills/script-execution-instructions.md deleted file mode 120000 index 8737e1e..0000000 --- a/.claude/rules/skills/script-execution-instructions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/script-execution-instructions.md \ No newline at end of file diff --git a/.claude/rules/skills/security-restrictions.md b/.claude/rules/skills/security-restrictions.md deleted file mode 120000 index 2a53baa..0000000 --- a/.claude/rules/skills/security-restrictions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/security-restrictions.md \ No newline at end of file diff --git a/.claude/rules/skills/skill-composition.md b/.claude/rules/skills/skill-composition.md deleted file mode 120000 index 3877b05..0000000 --- a/.claude/rules/skills/skill-composition.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/skill-composition.md \ No newline at end of file diff --git a/.claude/rules/skills/skill-decomposition.md b/.claude/rules/skills/skill-decomposition.md deleted file mode 120000 index c55b7c1..0000000 --- a/.claude/rules/skills/skill-decomposition.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/skill-decomposition.md \ No newline at end of file diff --git a/.claude/rules/skills/skill-description-frontmatter.md b/.claude/rules/skills/skill-description-frontmatter.md deleted file mode 120000 index c7bfd81..0000000 --- a/.claude/rules/skills/skill-description-frontmatter.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/skill-description-frontmatter.md \ No newline at end of file diff --git a/.claude/rules/skills/skill-reference-files.md b/.claude/rules/skills/skill-reference-files.md deleted file mode 120000 index 8c9e218..0000000 --- a/.claude/rules/skills/skill-reference-files.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/skill-reference-files.md \ No newline at end of file diff --git a/.claude/rules/skills/success-criteria-and-testing.md b/.claude/rules/skills/success-criteria-and-testing.md deleted file mode 120000 index 2194165..0000000 --- a/.claude/rules/skills/success-criteria-and-testing.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/success-criteria-and-testing.md \ No newline at end of file diff --git a/.claude/rules/skills/troubleshooting.md b/.claude/rules/skills/troubleshooting.md deleted file mode 120000 index a4e9413..0000000 --- a/.claude/rules/skills/troubleshooting.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/troubleshooting.md \ No newline at end of file diff --git a/.claude/rules/skills/use-case-planning.md b/.claude/rules/skills/use-case-planning.md deleted file mode 120000 index f19181d..0000000 --- a/.claude/rules/skills/use-case-planning.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/use-case-planning.md \ No newline at end of file diff --git a/.claude/rules/skills/workflow-patterns.md b/.claude/rules/skills/workflow-patterns.md deleted file mode 120000 index 6914390..0000000 --- a/.claude/rules/skills/workflow-patterns.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/workflow-patterns.md \ No newline at end of file diff --git a/.claude/rules/skills/writing-effective-instructions.md b/.claude/rules/skills/writing-effective-instructions.md deleted file mode 120000 index 530b07d..0000000 --- a/.claude/rules/skills/writing-effective-instructions.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/skill-building-guidance/writing-effective-instructions.md \ No newline at end of file From 76dedf3bbbe35a135fd845d764ba6cdbaa1c6b93 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 26 May 2026 09:59:28 -0600 Subject: [PATCH 2/4] .claude/rules: replace agent guidance symlinks with index file Replace the 5 one-symlink-per-doc entries under .claude/rules/agents/ with a single .claude/rules/agent-building-guidelines.md index file. The index carries paths: "plugin/agents/**/*.md" so it loads only when an agent file is being read, and lists every guidance doc with a 1-3 sentence description so Claude can pick the relevant subset to open on demand instead of loading all 5 docs at once. Matches the layout introduced in the previous commit for skill-building guidance. --- .claude/rules/agent-building-guidelines.md | 37 +++++++++++++++++++ .claude/rules/agents/agent-domain-focus.md | 1 - .claude/rules/agents/agent-external-files.md | 1 - .claude/rules/agents/agent-model-selection.md | 1 - .claude/rules/agents/graceful-degradation.md | 1 - .claude/rules/agents/multi-agent-economics.md | 1 - 6 files changed, 37 insertions(+), 5 deletions(-) create mode 100644 .claude/rules/agent-building-guidelines.md delete mode 120000 .claude/rules/agents/agent-domain-focus.md delete mode 120000 .claude/rules/agents/agent-external-files.md delete mode 120000 .claude/rules/agents/agent-model-selection.md delete mode 120000 .claude/rules/agents/graceful-degradation.md delete mode 120000 .claude/rules/agents/multi-agent-economics.md diff --git a/.claude/rules/agent-building-guidelines.md b/.claude/rules/agent-building-guidelines.md new file mode 100644 index 0000000..756e49f --- /dev/null +++ b/.claude/rules/agent-building-guidelines.md @@ -0,0 +1,37 @@ +--- +paths: + - "plugin/agents/**/*.md" +--- + +# Agent-building guidelines index + +You are reading this file because Claude Code loaded it as a path-scoped +rule — you just read or are about to read a file under `plugin/agents/`. + +This file is an **index**, not guidance. Each entry below points to a +canonical agent-building guidance document with a short description of +what it covers and when it applies. + +Agent-building guidance lives in `docs/guidance/agent-building-guidelines/` +and is exposed to Claude Code through this single index file. The full +text of any individual guidance doc is loaded only when you decide it +applies and use the Read tool to open it. This keeps context lean and +lets you make a relevance decision before paying the token cost. + +**Do not read every linked document.** For the specific task you are +doing right now, scan the descriptions and identify only the documents +that are clearly relevant. Then use the Read tool to open just those +files. If no entry is clearly relevant, do not open any of them. + +If you are unsure whether a guidance doc applies, do not open it. The +author of the work can prompt you to load a specific doc if needed. +Loading guidance that does not apply burns context and dilutes attention +on the parts that do. + +## Available guidance + +- [Domain Focus in Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-domain-focus.md) — Why agents perform better with narrow domain vocabulary (the 15-year-practitioner test) and how to write agent descriptions that route to expert-level training data. Read when authoring or revising an agent's description, role, or trigger vocabulary. +- [External File References in Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-external-files.md) — Why agent `.md` files must be entirely self-contained: no `references/` folder, no `scripts/`, no context-injection commands. Read when tempted to extract content from an agent definition into a companion file. +- [Choosing the Right Model for Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-model-selection.md) — How to match the `model:` frontmatter (opus, sonnet, haiku, inherit) to the agent's task complexity. Cost is not a factor — capability is. Read when creating a new agent or when an agent's quality or speed feels mismatched. +- [Graceful Degradation](../../docs/guidance/agent-building-guidelines/graceful-degradation.md) — How agents should detect missing tools (git, CLIs, external APIs) inline, skip dependent steps, and note the limitation in their output. Read when an agent uses any tool that might be absent in the calling skill's environment. +- [Multi-Agent Economics](../../docs/guidance/agent-building-guidelines/multi-agent-economics.md) — The decision framework for when adding agents is justified versus wasteful, including the escalation cascade from single agent up. Read before adding a new `Agent` dispatch to a skill, or when reviewing whether an existing fleet of agents could be collapsed. diff --git a/.claude/rules/agents/agent-domain-focus.md b/.claude/rules/agents/agent-domain-focus.md deleted file mode 120000 index bfcdf1d..0000000 --- a/.claude/rules/agents/agent-domain-focus.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/agent-building-guidelines/agent-domain-focus.md \ No newline at end of file diff --git a/.claude/rules/agents/agent-external-files.md b/.claude/rules/agents/agent-external-files.md deleted file mode 120000 index 198e967..0000000 --- a/.claude/rules/agents/agent-external-files.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/agent-building-guidelines/agent-external-files.md \ No newline at end of file diff --git a/.claude/rules/agents/agent-model-selection.md b/.claude/rules/agents/agent-model-selection.md deleted file mode 120000 index d7cee1d..0000000 --- a/.claude/rules/agents/agent-model-selection.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/agent-building-guidelines/agent-model-selection.md \ No newline at end of file diff --git a/.claude/rules/agents/graceful-degradation.md b/.claude/rules/agents/graceful-degradation.md deleted file mode 120000 index 847bc6f..0000000 --- a/.claude/rules/agents/graceful-degradation.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/agent-building-guidelines/graceful-degradation.md \ No newline at end of file diff --git a/.claude/rules/agents/multi-agent-economics.md b/.claude/rules/agents/multi-agent-economics.md deleted file mode 120000 index d78a6e9..0000000 --- a/.claude/rules/agents/multi-agent-economics.md +++ /dev/null @@ -1 +0,0 @@ -../../../docs/guidance/agent-building-guidelines/multi-agent-economics.md \ No newline at end of file From dbe6893945e2a464bda175c3293a7ac56357c535 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 26 May 2026 10:04:02 -0600 Subject: [PATCH 3/4] .claude/rules: align skills index with canonical template Move .claude/rules/skill-building-guidance.md to its canonical location under .claude/rules/coding-standards/plugin-skills.md, and use the template's verbatim instruction paragraph and "## Available standards" section heading. The previous file paraphrased the template (saying "guidance" / "## Available guidance" instead of "standard" / "## Available standards"), which violated Step 7.3 and Step 10.4 of the coding-standard skill, both of which require the instruction paragraph to be unchanged from the template. Entries are sorted alphabetically by title. --- .../rules/coding-standards/plugin-skills.md | 59 +++++++++++++++++++ .claude/rules/skill-building-guidance.md | 56 ------------------ 2 files changed, 59 insertions(+), 56 deletions(-) create mode 100644 .claude/rules/coding-standards/plugin-skills.md delete mode 100644 .claude/rules/skill-building-guidance.md diff --git a/.claude/rules/coding-standards/plugin-skills.md b/.claude/rules/coding-standards/plugin-skills.md new file mode 100644 index 0000000..861ae7f --- /dev/null +++ b/.claude/rules/coding-standards/plugin-skills.md @@ -0,0 +1,59 @@ +--- +paths: + - "plugin/skills/**/*.md" + - "plugin/skills/**/scripts/**" +--- + +# Plugin skills coding standards index + +You are reading this file because Claude Code loaded it as a path-scoped +rule — you just read or are about to read a file matching one of the +globs in this file's `paths:` frontmatter. + +This file is an **index**, not a standard. Each entry below points to a +canonical coding standard with a short description of what it covers and +when it applies. + +Coding standards for this project live in their canonical documentation +directory (usually `docs/coding-standards/`) and are exposed to Claude +Code through per-file-type index files under +`.claude/rules/coding-standards/`. The full text of a standard is loaded +only when you decide it applies and use the Read tool to open it. This +keeps context lean and lets you make a relevance decision before paying +the token cost. + +**Do not read every linked standard.** For the specific task you are +doing right now, scan the descriptions and identify only the standards +that are clearly relevant. Then use the Read tool to open just those +files. If no entry is clearly relevant, do not open any of them. + +If you are unsure whether a standard applies, do not open it. The +author of the work can prompt you to load a specific standard if needed. +Loading standards that do not apply burns context and dilutes attention +on the ones that do. + +## Available standards + +- [`AskUserQuestion` in Skill `allowed-tools`](../../../docs/guidance/skill-building-guidance/allowed-tools-AskUserQuestion.md) — Why `AskUserQuestion` must never appear in a skill's `allowed-tools` frontmatter. Read when adding or editing the `allowed-tools` line in a SKILL.md. +- [Bash Permission Patterns in `allowed-tools`](../../../docs/guidance/skill-building-guidance/allowed-tools-bash-permissions.md) — Syntax and granularity rules for `Bash(...)` entries in `allowed-tools`. Read when adding, removing, or scoping bash commands in a SKILL.md. +- [Claude Cowork — Complete Reference](../../../docs/guidance/skill-building-guidance/cowork-specific-skill-instructions.md) — Reference for skills targeted at the Claude Cowork desktop product (not developer workflows). Read only when authoring a skill that ships for Cowork users. +- [Context Hygiene](../../../docs/guidance/skill-building-guidance/context-hygiene.md) — The attention-budget reasoning behind progressive disclosure, frontmatter conciseness, and reference extraction. Read when deciding whether content earns its place in a SKILL.md or should move to `references/`. +- [Context Injection Commands in Skill Files](../../../docs/guidance/skill-building-guidance/context-injection-commands.md) — Using `` !`command` `` syntax to inject runtime context at skill load time. Read when adding or debugging a `## Project Context` block or any inline shell command in a skill. +- [Documentation Maintenance](../../../docs/guidance/skill-building-guidance/documentation-maintenance.md) — Auditing skills so their instructions don't silently rot when the underlying tooling, agents, or repository conventions change. Read when editing a skill that hasn't been touched in a while, or when downstream code has changed shape. +- [Dynamic Project Discovery](../../../docs/guidance/skill-building-guidance/dynamic-project-discovery.md) — Rules for discovering branches, tool availability, and project structure at runtime instead of hardcoding. Read when a skill needs to know the default branch, project layout, or which CLIs are installed. +- [Graceful Degradation](../../../docs/guidance/skill-building-guidance/graceful-degradation.md) — Detecting partial environments (missing git history, absent project config) and selecting a named execution mode rather than hard-failing. Read when a skill must still produce useful output in incomplete environments. +- [Hardening: Fuzzy vs. Deterministic Steps](../../../docs/guidance/skill-building-guidance/hardening-fuzzy-vs-deterministic.md) — Decision framework for classifying steps as fuzzy reasoning (stay in SKILL.md) or deterministic operations (extract to scripts). Read when a SKILL.md has steps that could become flaky or when deciding to add a script. +- [Naming Conventions](../../../docs/guidance/skill-building-guidance/naming-conventions.md) — Rules for naming plugins, skills, directories, and the `name` field so users can discover and recognize skills. Read when creating a new skill, renaming an existing one, or changing a plugin directory. +- [Optional Git Repositories](../../../docs/guidance/skill-building-guidance/optional-git-repositories.md) — Why analysis skills should treat git as optional and how to detect git state safely. Read when a skill uses any `git` command or assumes a repository, remote, or branch exists. +- [Progressive Disclosure](../../../docs/guidance/skill-building-guidance/progressive-disclosure.md) — The three-level architecture (frontmatter, SKILL.md body, `references/`) and rules for what belongs in each level. Read when deciding where new content goes in a skill, or when a SKILL.md is growing too large. +- [Script Execution Instructions in SKILL.md](../../../docs/guidance/skill-building-guidance/script-execution-instructions.md) — How to describe script invocations as numbered prose instructions, not fenced code blocks, with explicit `${CLAUDE_SKILL_DIR}` paths. Read when a skill calls a shell script from its steps. +- [Security Restrictions](../../../docs/guidance/skill-building-guidance/security-restrictions.md) — Frontmatter restrictions that prevent prompt injection and silent failures, including no XML angle brackets in YAML. Read when editing any field in a skill's YAML frontmatter. +- [Skill Composition](../../../docs/guidance/skill-building-guidance/skill-composition.md) — The rule against sub-skill calls (skills invoking other skills via the Skill tool) and what to do instead. Read before reaching for a sub-skill call. +- [Skill Decomposition](../../../docs/guidance/skill-building-guidance/skill-decomposition.md) — Single-responsibility rules for skills and how to split a skill that has grown to do too much. Read when a skill's description starts to list multiple unrelated outcomes. +- [Skill Description Frontmatter](../../../docs/guidance/skill-building-guidance/skill-description-frontmatter.md) — How the `description` field competes for selection across all loaded skills and how to write descriptions that trigger correctly without false positives. Read when writing or revising a `description:` line. +- [Skill Reference Files](../../../docs/guidance/skill-building-guidance/skill-reference-files.md) — How `references/` files work as the third level of progressive disclosure and what content belongs there versus in SKILL.md. Read when extracting templates, checklists, or domain knowledge out of a SKILL.md. +- [Success Criteria and Testing](../../../docs/guidance/skill-building-guidance/success-criteria-and-testing.md) — The three test types (triggering, functional, comparative) and how to validate a skill works. Read after building a skill, or when a skill is producing inconsistent results. +- [Troubleshooting](../../../docs/guidance/skill-building-guidance/troubleshooting.md) — Common symptoms encountered when building or using skills, organized by failure mode, with the likely cause and fix. Read when a skill won't upload, won't trigger, hangs on a permission prompt, or behaves unexpectedly. +- [Use Case Planning](../../../docs/guidance/skill-building-guidance/use-case-planning.md) — The pre-development step of defining 2-3 concrete use cases before writing a SKILL.md. Read when starting a new skill from scratch. +- [Workflow Patterns](../../../docs/guidance/skill-building-guidance/workflow-patterns.md) — The four structural patterns that appear across well-built skills and how to compose them within a single SKILL.md. Read when designing or refactoring the step structure of a skill. +- [Writing Effective Instructions](../../../docs/guidance/skill-building-guidance/writing-effective-instructions.md) — Rules for writing the SKILL.md body so Claude follows the workflow reliably: specificity, recency, structure, action verbs. Read when the SKILL.md body is being authored or when steps are producing inconsistent results. diff --git a/.claude/rules/skill-building-guidance.md b/.claude/rules/skill-building-guidance.md deleted file mode 100644 index 7a18412..0000000 --- a/.claude/rules/skill-building-guidance.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -paths: - - "plugin/skills/**/*.md" - - "plugin/skills/**/scripts/**" ---- - -# Skill-building guidance index - -You are reading this file because Claude Code loaded it as a path-scoped -rule — you just read or are about to read a file under `plugin/skills/`. - -This file is an **index**, not guidance. Each entry below points to a -canonical skill-building guidance document with a short description of -what it covers and when it applies. - -Skill-building guidance lives in `docs/guidance/skill-building-guidance/` -and is exposed to Claude Code through this single index file. The full -text of any individual guidance doc is loaded only when you decide it -applies and use the Read tool to open it. This keeps context lean and -lets you make a relevance decision before paying the token cost. - -**Do not read every linked document.** For the specific task you are -doing right now, scan the descriptions and identify only the documents -that are clearly relevant. Then use the Read tool to open just those -files. If no entry is clearly relevant, do not open any of them. - -If you are unsure whether a guidance doc applies, do not open it. The -author of the work can prompt you to load a specific doc if needed. -Loading guidance that does not apply burns context and dilutes attention -on the parts that do. - -## Available guidance - -- [`AskUserQuestion` in Skill `allowed-tools`](../../docs/guidance/skill-building-guidance/allowed-tools-AskUserQuestion.md) — Why `AskUserQuestion` must never appear in a skill's `allowed-tools` frontmatter. Read when adding or editing the `allowed-tools` line in a SKILL.md. -- [Bash Permission Patterns in `allowed-tools`](../../docs/guidance/skill-building-guidance/allowed-tools-bash-permissions.md) — Syntax and granularity rules for `Bash(...)` entries in `allowed-tools`. Read when adding, removing, or scoping bash commands in a SKILL.md. -- [Context Hygiene](../../docs/guidance/skill-building-guidance/context-hygiene.md) — The attention-budget reasoning behind progressive disclosure, frontmatter conciseness, and reference extraction. Read when deciding whether content earns its place in a SKILL.md or should move to `references/`. -- [Context Injection Commands in Skill Files](../../docs/guidance/skill-building-guidance/context-injection-commands.md) — Using `` !`command` `` syntax to inject runtime context at skill load time. Read when adding or debugging a `## Project Context` block or any inline shell command in a skill. -- [Claude Cowork — Complete Reference](../../docs/guidance/skill-building-guidance/cowork-specific-skill-instructions.md) — Reference for skills targeted at the Claude Cowork desktop product (not developer workflows). Read only when authoring a skill that ships for Cowork users. -- [Documentation Maintenance](../../docs/guidance/skill-building-guidance/documentation-maintenance.md) — Auditing skills so their instructions don't silently rot when the underlying tooling, agents, or repository conventions change. Read when editing a skill that hasn't been touched in a while, or when downstream code has changed shape. -- [Dynamic Project Discovery](../../docs/guidance/skill-building-guidance/dynamic-project-discovery.md) — Rules for discovering branches, tool availability, and project structure at runtime instead of hardcoding. Read when a skill needs to know the default branch, project layout, or which CLIs are installed. -- [Graceful Degradation](../../docs/guidance/skill-building-guidance/graceful-degradation.md) — Detecting partial environments (missing git history, absent project config) and selecting a named execution mode rather than hard-failing. Read when a skill must still produce useful output in incomplete environments. -- [Hardening: Fuzzy vs. Deterministic Steps](../../docs/guidance/skill-building-guidance/hardening-fuzzy-vs-deterministic.md) — Decision framework for classifying steps as fuzzy reasoning (stay in SKILL.md) or deterministic operations (extract to scripts). Read when a SKILL.md has steps that could become flaky or when deciding to add a script. -- [Naming Conventions](../../docs/guidance/skill-building-guidance/naming-conventions.md) — Rules for naming plugins, skills, directories, and the `name` field so users can discover and recognize skills. Read when creating a new skill, renaming an existing one, or changing a plugin directory. -- [Optional Git Repositories](../../docs/guidance/skill-building-guidance/optional-git-repositories.md) — Why analysis skills should treat git as optional and how to detect git state safely. Read when a skill uses any `git` command or assumes a repository, remote, or branch exists. -- [Progressive Disclosure](../../docs/guidance/skill-building-guidance/progressive-disclosure.md) — The three-level architecture (frontmatter, SKILL.md body, `references/`) and rules for what belongs in each level. Read when deciding where new content goes in a skill, or when a SKILL.md is growing too large. -- [Script Execution Instructions in SKILL.md](../../docs/guidance/skill-building-guidance/script-execution-instructions.md) — How to describe script invocations as numbered prose instructions, not fenced code blocks, with explicit `${CLAUDE_SKILL_DIR}` paths. Read when a skill calls a shell script from its steps. -- [Security Restrictions](../../docs/guidance/skill-building-guidance/security-restrictions.md) — Frontmatter restrictions that prevent prompt injection and silent failures, including no XML angle brackets in YAML. Read when editing any field in a skill's YAML frontmatter. -- [Skill Composition](../../docs/guidance/skill-building-guidance/skill-composition.md) — The rule against sub-skill calls (skills invoking other skills via the Skill tool) and what to do instead. Read before reaching for a sub-skill call. -- [Skill Decomposition](../../docs/guidance/skill-building-guidance/skill-decomposition.md) — Single-responsibility rules for skills and how to split a skill that has grown to do too much. Read when a skill's description starts to list multiple unrelated outcomes. -- [Skill Description Frontmatter](../../docs/guidance/skill-building-guidance/skill-description-frontmatter.md) — How the `description` field competes for selection across all loaded skills and how to write descriptions that trigger correctly without false positives. Read when writing or revising a `description:` line. -- [Skill Reference Files](../../docs/guidance/skill-building-guidance/skill-reference-files.md) — How `references/` files work as the third level of progressive disclosure and what content belongs there versus in SKILL.md. Read when extracting templates, checklists, or domain knowledge out of a SKILL.md. -- [Success Criteria and Testing](../../docs/guidance/skill-building-guidance/success-criteria-and-testing.md) — The three test types (triggering, functional, comparative) and how to validate a skill works. Read after building a skill, or when a skill is producing inconsistent results. -- [Troubleshooting](../../docs/guidance/skill-building-guidance/troubleshooting.md) — Common symptoms encountered when building or using skills, organized by failure mode, with the likely cause and fix. Read when a skill won't upload, won't trigger, hangs on a permission prompt, or behaves unexpectedly. -- [Use Case Planning](../../docs/guidance/skill-building-guidance/use-case-planning.md) — The pre-development step of defining 2-3 concrete use cases before writing a SKILL.md. Read when starting a new skill from scratch. -- [Workflow Patterns](../../docs/guidance/skill-building-guidance/workflow-patterns.md) — The four structural patterns that appear across well-built skills and how to compose them within a single SKILL.md. Read when designing or refactoring the step structure of a skill. -- [Writing Effective Instructions](../../docs/guidance/skill-building-guidance/writing-effective-instructions.md) — Rules for writing the SKILL.md body so Claude follows the workflow reliably: specificity, recency, structure, action verbs. Read when the SKILL.md body is being authored or when steps are producing inconsistent results. From b81689c2d2b770ce9d934c8c3766f69fd520e101 Mon Sep 17 00:00:00 2001 From: River Bailey Date: Tue, 26 May 2026 10:05:41 -0600 Subject: [PATCH 4/4] .claude/rules: align agents index with canonical template Move .claude/rules/agent-building-guidelines.md to its canonical location under .claude/rules/coding-standards/plugin-agents.md, and use the template's verbatim instruction paragraph and "## Available standards" section heading. Matches the realignment applied in the previous commit for the plugin-skills index. Entries are sorted alphabetically by title. --- .claude/rules/agent-building-guidelines.md | 37 ----------------- .../rules/coding-standards/plugin-agents.md | 40 +++++++++++++++++++ 2 files changed, 40 insertions(+), 37 deletions(-) delete mode 100644 .claude/rules/agent-building-guidelines.md create mode 100644 .claude/rules/coding-standards/plugin-agents.md diff --git a/.claude/rules/agent-building-guidelines.md b/.claude/rules/agent-building-guidelines.md deleted file mode 100644 index 756e49f..0000000 --- a/.claude/rules/agent-building-guidelines.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -paths: - - "plugin/agents/**/*.md" ---- - -# Agent-building guidelines index - -You are reading this file because Claude Code loaded it as a path-scoped -rule — you just read or are about to read a file under `plugin/agents/`. - -This file is an **index**, not guidance. Each entry below points to a -canonical agent-building guidance document with a short description of -what it covers and when it applies. - -Agent-building guidance lives in `docs/guidance/agent-building-guidelines/` -and is exposed to Claude Code through this single index file. The full -text of any individual guidance doc is loaded only when you decide it -applies and use the Read tool to open it. This keeps context lean and -lets you make a relevance decision before paying the token cost. - -**Do not read every linked document.** For the specific task you are -doing right now, scan the descriptions and identify only the documents -that are clearly relevant. Then use the Read tool to open just those -files. If no entry is clearly relevant, do not open any of them. - -If you are unsure whether a guidance doc applies, do not open it. The -author of the work can prompt you to load a specific doc if needed. -Loading guidance that does not apply burns context and dilutes attention -on the parts that do. - -## Available guidance - -- [Domain Focus in Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-domain-focus.md) — Why agents perform better with narrow domain vocabulary (the 15-year-practitioner test) and how to write agent descriptions that route to expert-level training data. Read when authoring or revising an agent's description, role, or trigger vocabulary. -- [External File References in Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-external-files.md) — Why agent `.md` files must be entirely self-contained: no `references/` folder, no `scripts/`, no context-injection commands. Read when tempted to extract content from an agent definition into a companion file. -- [Choosing the Right Model for Agent Definitions](../../docs/guidance/agent-building-guidelines/agent-model-selection.md) — How to match the `model:` frontmatter (opus, sonnet, haiku, inherit) to the agent's task complexity. Cost is not a factor — capability is. Read when creating a new agent or when an agent's quality or speed feels mismatched. -- [Graceful Degradation](../../docs/guidance/agent-building-guidelines/graceful-degradation.md) — How agents should detect missing tools (git, CLIs, external APIs) inline, skip dependent steps, and note the limitation in their output. Read when an agent uses any tool that might be absent in the calling skill's environment. -- [Multi-Agent Economics](../../docs/guidance/agent-building-guidelines/multi-agent-economics.md) — The decision framework for when adding agents is justified versus wasteful, including the escalation cascade from single agent up. Read before adding a new `Agent` dispatch to a skill, or when reviewing whether an existing fleet of agents could be collapsed. diff --git a/.claude/rules/coding-standards/plugin-agents.md b/.claude/rules/coding-standards/plugin-agents.md new file mode 100644 index 0000000..a43b4c8 --- /dev/null +++ b/.claude/rules/coding-standards/plugin-agents.md @@ -0,0 +1,40 @@ +--- +paths: + - "plugin/agents/**/*.md" +--- + +# Plugin agents coding standards index + +You are reading this file because Claude Code loaded it as a path-scoped +rule — you just read or are about to read a file matching one of the +globs in this file's `paths:` frontmatter. + +This file is an **index**, not a standard. Each entry below points to a +canonical coding standard with a short description of what it covers and +when it applies. + +Coding standards for this project live in their canonical documentation +directory (usually `docs/coding-standards/`) and are exposed to Claude +Code through per-file-type index files under +`.claude/rules/coding-standards/`. The full text of a standard is loaded +only when you decide it applies and use the Read tool to open it. This +keeps context lean and lets you make a relevance decision before paying +the token cost. + +**Do not read every linked standard.** For the specific task you are +doing right now, scan the descriptions and identify only the standards +that are clearly relevant. Then use the Read tool to open just those +files. If no entry is clearly relevant, do not open any of them. + +If you are unsure whether a standard applies, do not open it. The +author of the work can prompt you to load a specific standard if needed. +Loading standards that do not apply burns context and dilutes attention +on the ones that do. + +## Available standards + +- [Choosing the Right Model for Agent Definitions](../../../docs/guidance/agent-building-guidelines/agent-model-selection.md) — How to match the `model:` frontmatter (opus, sonnet, haiku, inherit) to the agent's task complexity. Cost is not a factor — capability is. Read when creating a new agent or when an agent's quality or speed feels mismatched. +- [Domain Focus in Agent Definitions](../../../docs/guidance/agent-building-guidelines/agent-domain-focus.md) — Why agents perform better with narrow domain vocabulary (the 15-year-practitioner test) and how to write agent descriptions that route to expert-level training data. Read when authoring or revising an agent's description, role, or trigger vocabulary. +- [External File References in Agent Definitions](../../../docs/guidance/agent-building-guidelines/agent-external-files.md) — Why agent `.md` files must be entirely self-contained: no `references/` folder, no `scripts/`, no context-injection commands. Read when tempted to extract content from an agent definition into a companion file. +- [Graceful Degradation](../../../docs/guidance/agent-building-guidelines/graceful-degradation.md) — How agents should detect missing tools (git, CLIs, external APIs) inline, skip dependent steps, and note the limitation in their output. Read when an agent uses any tool that might be absent in the calling skill's environment. +- [Multi-Agent Economics](../../../docs/guidance/agent-building-guidelines/multi-agent-economics.md) — The decision framework for when adding agents is justified versus wasteful, including the escalation cascade from single agent up. Read before adding a new `Agent` dispatch to a skill, or when reviewing whether an existing fleet of agents could be collapsed.