docs(tool-guides): add skills/sub-agents/teams and improve hooks guidance

andkirby · andkirby · commit 3fa8f49bdaf2 · 2026-02-16T23:52:54.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -21,3 +21,11 @@ guide-LLiMes is a framework for building LLM coding guidelines that improve outp
 - Start with 3 must-have guidelines.
 - Expand incrementally as repeat failure patterns appear.
 - Add should-have and nice-to-have guidance when the pain justifies the extra context cost.
+
+## Authoring Pattern (Default)
+
+For tool or feature documentation, structure content in this order:
+
+1. Problem: current user pain or failure pattern.
+2. Value: what improves after applying the guidance.
+3. When to use: concrete decision cues and scenarios.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -68,6 +68,31 @@ PR checklist:
 - No duplicated rules when automation/checks already enforce behavior
 - References and internal links are valid
 
+## Default Writing Pattern
+
+For feature/tool sections, prefer this order:
+
+1. **Problem**: what pain or failure pattern the reader has now
+2. **Value**: what improves if they apply this guidance
+3. **When to use**: decision cues and concrete scenarios
+
+This structure keeps content user-outcome driven instead of feature-list driven.
+
+Reusable mini-template:
+
+```markdown
+## Why this matters
+[problem]
+
+## What value it gives
+[outcome]
+
+## When to use it
+- [scenario 1]
+- [scenario 2]
+- [scenario 3]
+```
+
 ## Review Criteria
 
 Reviewers prioritize:
@@ -97,4 +122,3 @@ Open the local URL shown by Jekyll and verify navigation, links, and page readab
 - Assume good intent and review the idea, not the person
 - Prefer incremental improvements over broad speculative rewrites
 - Keep discussion anchored to improving output quality in real projects
-
diff --git a/docs/00-introduction/tool-landscape.md b/docs/00-introduction/tool-landscape.md
@@ -32,6 +32,13 @@ What varies is the file location, format details, and how much control you have
 - **Key feature**: Hierarchical — subdirectory CLAUDE.md files add context for that part of the codebase
 - **Limit**: ~150-200 effective instructions before reliability drops
 
+Claude Code also has strong workflow primitives:
+
+- **[Hooks](../05-tool-guides/hooks.md)** for runtime quality enforcement
+- **[Skills](../05-tool-guides/skills.md)** for reusable task playbooks
+- **[Sub-agents](../05-tool-guides/sub-agents.md)** for delegated specialist execution
+- **[Agent teams](../05-tool-guides/agent-teams.md)** for teammate-style multi-agent collaboration
+
 ```
 my-project/
 ├── CLAUDE.md              # Project-wide guidelines
diff --git a/docs/05-tool-guides/agent-teams.md b/docs/05-tool-guides/agent-teams.md
@@ -0,0 +1,66 @@
+---
+layout: default
+title: Agent Teams
+nav_order: 5
+parent: Tool Guides
+---
+
+# Agent Teams — Let Specialists Collaborate as a System
+
+## Why Teams Are Helpful
+
+A single agent can execute many tasks, but complex work often benefits from multiple specialists coordinating: architecture, implementation, QA, and documentation.
+
+Agent teams help when:
+
+- the task spans multiple disciplines
+- you need parallel work with role-specific quality bars
+- one coordinator should keep global constraints while specialists execute
+
+This makes "agents talking to each other" explicit and structured instead of ad hoc.
+
+## Claude Code Agent Teams
+
+Claude Code supports team definitions in:
+
+- `.claude/agents/team/**/*.md`
+
+The tooling includes:
+
+- `/agents` to manage agents
+- `/agents-team` to create and manage agent teams
+
+Team packs can define:
+
+- a main architecture/orchestrator agent
+- specialist teammate agents
+- collaboration patterns between teammates
+
+## Team Design Pattern
+
+Start with three roles:
+
+1. **Coordinator** — owns goals, constraints, and final synthesis
+2. **Builder** — implements changes and reports verification
+3. **Reviewer** — validates risks, regressions, and policy alignment
+
+Add more roles only when repeated bottlenecks appear.
+
+## When to Use Teams vs Sub-Agents
+
+Use **sub-agents** when one primary agent can still coordinate effectively and you only need targeted delegation.
+
+Use **agent teams** when collaboration itself is the core challenge and role boundaries should be persistent.
+
+## Common Mistakes
+
+**Too many roles too early.** Start lean; scale roles from real pain points.
+
+**Role overlap.** If two teammates own the same decision, accountability becomes unclear.
+
+**No integration checkpoints.** Require merge checkpoints and explicit handoffs.
+
+## References
+
+- [Claude Code: Agent teams (official)](https://code.claude.com/docs/en/agent-teams)
+- [External References](../references.md)
diff --git a/docs/05-tool-guides/agents-md.md b/docs/05-tool-guides/agents-md.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: AGENTS.md
-nav_order: 5
+nav_order: 8
 parent: Tool Guides
 ---
 
diff --git a/docs/05-tool-guides/claude-code.md b/docs/05-tool-guides/claude-code.md
@@ -86,9 +86,13 @@ project/
 
 ## Key Features
 
-**Skills**: Claude Code supports custom skills — reusable command patterns stored in `.claude/skills/`. Use these for repetitive workflows like "write tests for this module" or "review this PR."
+**Skills**: Capture repeatable workflows once and reuse them across tasks. This reduces prompt repetition and increases consistency. See the [Skills Guide](skills.md).
 
-**Hooks**: Shell commands that run automatically before or after tool calls. Useful for enforcing guardrails programmatically (e.g., run linter after every file edit). See the [Hooks Guide](hooks.md).
+**Hooks**: Enforce deterministic checks around editing and execution. This closes the gap between instructions and actual runtime behavior. See the [Hooks Guide](hooks.md).
+
+**Sub-agents**: Delegate larger work units to specialized agents while keeping the main chat focused on coordination and decisions. See the [Sub-Agents Guide](sub-agents.md).
+
+**Agent teams**: Define teammate-style specialist collaboration for complex, multi-role tasks. See the [Agent Teams Guide](agent-teams.md).
 
 **File references**: Use `@filename` in CLAUDE.md to reference other documentation files (up to 5 levels deep).
 
diff --git a/docs/05-tool-guides/cursor.md b/docs/05-tool-guides/cursor.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Cursor
-nav_order: 3
+nav_order: 6
 parent: Tool Guides
 ---
 
diff --git a/docs/05-tool-guides/github-copilot.md b/docs/05-tool-guides/github-copilot.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: GitHub Copilot
-nav_order: 4
+nav_order: 7
 parent: Tool Guides
 ---
 
diff --git a/docs/05-tool-guides/hooks.md b/docs/05-tool-guides/hooks.md
@@ -9,54 +9,126 @@ parent: Tool Guides
 
 ## Why This Matters
 
-Guidelines describe what good output looks like. Hooks enforce it automatically while the model is working. This closes the gap between "the model was told" and "the model actually did it."
+Guidelines say what should happen. Hooks make it happen automatically while the model is editing code and running tools.
 
-Hooks are especially useful for:
+Use hooks for:
+- **Post-edit quality checks** (format, lint, typecheck, tests)
+- **Safety boundaries** (protected paths, risky commands, secrets checks)
+- **Consistent workflows** (same checks every run, not reviewer-dependent)
 
-- **Post-edit validation** — run lint, type checks, tests, policy checks
-- **Safety boundaries** — block risky commands or protected-path edits
-- **Workflow consistency** — apply formatting and project checks every time
+## Helpfulness Map (Problem -> Hook Value)
 
-## What to Automate First
+| Team pain | Hook intervention | User-visible benefit |
+|---|---|---|
+| "The agent forgot lint/typecheck again" | `PostToolUse` checks after edits | Fewer review-round failures |
+| "Risky files changed without discussion" | `PreToolUse` policy guard | Earlier, clearer stop signals |
+| "Quality depends on who prompted better" | Standard hook scripts | More consistent output quality |
+| "Session quality drifts over time" | `Stop` / `SubagentStop` summaries | Better closure and handoff quality |
+
+## Claude Code Hook Model (Vendor Reference)
+
+Claude Code has first-class lifecycle hooks. In practice, this is the most complete built-in hook system across current coding-agent tools.
+
+### Supported lifecycle events
+
+- `PreToolUse` — before tool execution
+- `PostToolUse` — after tool execution
+- `Notification` — when Claude emits notifications
+- `UserPromptSubmit` — when the user submits a prompt
+- `Stop` — when Claude finishes responding
+- `SubagentStop` — when a subagent finishes
+- `PreCompact` — before context compaction
+
+### Hook handler types
+
+Claude supports multiple hook handler types:
+
+- **Command hooks** — run shell commands/scripts
+- **Prompt hooks** — inject natural-language guidance at hook time
+- **Agent hooks** — invoke a subagent to evaluate or gate behavior
+
+This makes hooks useful for both deterministic checks (scripts) and policy judgment flows (prompt/agent).
+
+### Configuration locations
+
+Claude supports hooks in multiple settings scopes:
 
-Start with low-friction checks that are fast and deterministic:
+- `~/.claude/settings.json` (user scope)
+- `.claude/settings.json` (project scope)
+- local/project variants as documented by Anthropic
 
-1. **Formatting and linting** after file edits
-2. **Type checks** before completion
-3. **Targeted tests** for modified modules
-4. **Policy checks** for protected files (migrations, CI, infra)
+### Matcher behavior
 
-If a check is slow or flaky, keep it in CI first and move it into hooks only when stable.
+For tool events, each hook can target a matcher:
 
-## Hook Design Pattern
+- exact tool name, for example `Bash`
+- pattern matcher, for example `Edit|Write`
+- wildcard matcher, `*`
 
-Treat hooks as a staged quality gate:
+If multiple hooks match, Claude executes all matching hooks.
 
-1. **Before action**: validate intent and boundaries
-2. **After action**: run local quality checks
-3. **On completion**: summarize failures and required fixes
+### Exit codes and control flow
 
-Keep hook scripts idempotent and explicit about exit codes:
+Hook return codes have explicit behavior:
 
-- `0` = pass
-- non-zero = fail and stop or request intervention
+- `0` = success
+- `2` = blocking error (show stderr to model)
+- other non-zero = non-blocking error
+
+Hooks can also emit structured JSON to control behavior and messaging to the model/user.
+
+### Minimal hook shape (illustrative)
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "./scripts/check-policy.sh" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "./scripts/check-changed.sh" }] }
+    ]
+  }
+}
+```
+
+The key idea is simple: guard before risky actions, validate after edits.
+
+## Cross-Tool Strategy
+
+Not every tool has Claude-style lifecycle hooks. Use a layered approach:
+
+1. **Native hooks when available** (Claude Code)
+2. **Wrapper scripts + pre-commit** for local deterministic checks
+3. **CI gates as final enforcement** for all tools
+
+Practical mapping:
+
+- **Claude Code**: native lifecycle hooks
+- **Cursor / Copilot / Codex-style workflows**: emulate hooks with command wrappers, task runners, pre-commit, and CI
+- **AGENTS.md**: policy only, no executable enforcement by itself
+
+## What to Automate First
 
-## Tool Notes
+1. Run formatter and linter after file edits
+2. Run type checks before task completion
+3. Run targeted tests for changed modules
+4. Add policy checks for protected files (migrations, CI, infra)
 
-- **Claude Code**: Has first-class lifecycle hooks. Use hooks for deterministic checks around edits and commands.
-- **Cursor / Copilot**: No universal built-in lifecycle hooks. Use wrapper scripts, pre-commit hooks, and CI gates to emulate hook behavior.
-- **AGENTS.md**: Defines policy and boundaries, but does not execute checks by itself. Pair it with executable hooks or CI.
+Keep local hook checks fast and deterministic. Push heavy integration checks to CI.
 
 ## Common Mistakes
 
-**Hook overload.** Too many heavy checks on every action hurts iteration speed and gets bypassed.
+**Hook overload.** Running slow full-suite checks on every action kills iteration speed.
 
-**Non-deterministic checks.** Flaky scripts erode trust; keep hooks deterministic and fast.
+**Flaky checks.** Teams stop trusting the hook output if failures are non-deterministic.
 
-**No fallback path.** If a hook fails, developers need clear remediation steps, not just "failed."
+**Unclear remediation.** A failure must say exactly what to do next.
 
-**Policy drift.** Hook behavior and written guardrails must match; update both together.
+**Policy drift.** Keep written guardrails and executable checks synchronized.
 
 ## References
 
+- [Claude Code: Automate workflows with hooks (official)](https://code.claude.com/docs/en/hooks-guide)
+- [Claude Code: Hooks reference (official)](https://code.claude.com/docs/en/hooks)
 - [External References](../references.md)
diff --git a/docs/05-tool-guides/index.md b/docs/05-tool-guides/index.md
@@ -36,6 +36,9 @@ For executable quality gates across tools, see [Hooks](hooks.md).
 
 - **Using Claude Code?** → [Claude Code Guide](claude-code.md)
 - **Want runtime quality gates?** → [Hooks Guide](hooks.md)
+- **Want reusable workflows instead of repeated prompts?** → [Skills Guide](skills.md)
+- **Working on bigger tasks and need delegation?** → [Sub-Agents Guide](sub-agents.md)
+- **Need specialist agents collaborating as a system?** → [Agent Teams Guide](agent-teams.md)
 - **Using Cursor?** → [Cursor Guide](cursor.md)
 - **Using GitHub Copilot?** → [GitHub Copilot Guide](github-copilot.md)
 - **Want a tool-agnostic format?** → [AGENTS.md Guide](agents-md.md)
diff --git a/docs/05-tool-guides/skills.md b/docs/05-tool-guides/skills.md
diff --git a/docs/05-tool-guides/sub-agents.md b/docs/05-tool-guides/sub-agents.md
diff --git a/docs/references.md b/docs/references.md
