---
alwaysApply: true
---

# Agent Usage Rules

## Orchestration Chain
When a command is invoked, follow the chain defined in its frontmatter:
- `agent:` field → MUST invoke that agent (or agents) by subagent_type name
- `skills:` field → MUST load those skills before/during agent work
- Commands without agent/skills fields → execute steps directly

This chain exists so skills are ACTUALLY USED, not just documented.
If you skip the chain, the user's investment in agents and skills is wasted.

## Skill Loading

Agents declare their skills in YAML frontmatter. Claude Code's native sub-agent loader parses the `skills:` field as a YAML list, resolves each name to a file on disk, and **injects the full skill content into the sub-agent's context at spawn** (per [Anthropic docs — Skills](https://code.claude.com/docs/en/skills) and [sub-agents](https://docs.claude.com/en/docs/claude-code/sub-agents)). Sub-agents do NOT inherit skills from the parent conversation — the frontmatter is the only channel.

**Authoritative layout — subdirectory + literal `SKILL.md`**:

```
.claude/skills/
├── coding-standards/
│   └── SKILL.md            ← entrypoint, literal uppercase filename
├── git-workflow/
│   └── SKILL.md
└── ...
```

Each skill is a directory, the entrypoint is always `SKILL.md` (literal uppercase), and the frontmatter must contain at minimum `name` and `description`. The project-scope path is `.claude/skills/<skill-name>/SKILL.md`. Flat files like `.claude/skills/<name>.md` are invisible to the loader — it silently injects nothing, no error.

**Authoritative syntax — YAML block list**:

```yaml
---
name: kody
skills:
  - coding-standards
  - receiving-code-review
  - git-workflow
---
```

**Anti-pattern 1 — comma-separated scalar** (parses as a single string, loader silently drops it):
```yaml
skills: coding-standards, receiving-code-review, git-workflow   # BROKEN
```

**Anti-pattern 2 — flat file layout** (loader resolves to `<name>/SKILL.md` and finds nothing):
```
.claude/skills/coding-standards.md   # BROKEN — invisible to the loader
```

Rules:
- MUST declare every skill used by an agent in its `skills:` frontmatter as a YAML list
- MUST place each skill at `.claude/skills/<name>/SKILL.md` with literal uppercase `SKILL.md` filename
- MUST quote `description:` fields that contain embedded colons (e.g. `"... Command: /foo. Severity: HIGH."`) — unquoted colons break YAML parsing silently
- MUST read skill files listed in **command** frontmatter when executing the command (commands run in the main session, not a sub-agent — the agent-level injection does not apply)
- MUST use skill-creator:skill-creator plugin for ALL skill work (create, edit, optimize, evaluate). Invoke via Skill tool: `skill: "skill-creator:skill-creator"`. The plugin handles: interview, drafting, test cases, evaluation loop, and description optimization. Never create skill files manually.
- Skills are domain knowledge — agents are the executors that USE that knowledge
- The catalog table below lists skills in comma-separated shorthand for human readability; the **authoritative declaration lives in each agent's frontmatter**
- Both layout and syntax are enforced by the agent frontmatter linter (run via `/medik`)

## Routing
- MUST use opus model for: arkitect, konstruct, spektr, alchemik
- MUST use sonnet model for: kody, typescript-reviewer, feniks, mekanik, kurator, arkonte, python-reviewer, almanak, kartograf, orakle, skavenger
- MUST use opus model for doks (documentation requires critical analysis across 4 layers)
- NEVER use haiku for code review, security analysis, or documentation updates

> Full Agent Catalog (16 agents with triggers, commands, and skills) and Auto-Invoke list — see [`.claude/agents/CATALOG.md`](../../agents/CATALOG.md). Single source-of-truth per ADR-035; auto-synced by `agent-metadata-sync` hook.

## Manual Rules
- MUST invoke kody before any commit via /chekpoint
- MUST invoke typescript-reviewer for .ts/.tsx/.js/.jsx file changes
- MUST invoke konstruct via /abra-kdabra — runs for every /abra-kdabra invocation
- MUST invoke arkitect before konstruct when /abra-kdabra task contains architecture signals
- MUST invoke almanak when referencing unfamiliar APIs or when no_context principle requires verification
- MUST invoke mekanik when TypeScript compilation or test runner reports failures (skip for obvious typos)
- MUST invoke doks after commits that add/remove agents, skills, or commands
- MUST use skill-creator:skill-creator plugin for any skill creation, editing, or evaluation. Invoke: `skill: "skill-creator:skill-creator"`. Never create skill files manually — the plugin handles structure, frontmatter, and description optimization.
- NEVER invoke arkitect for routine bug fixes or small features
- NEVER invoke alchemik without explicit /evolve command
- NEVER invoke kartograf without explicit /skanner command (tests are expensive)
- NEVER invoke kurator without explicit /medik clean command
- MUST invoke skavenger via /skavenger for multi-source investigation; NEVER fall back to raw WebSearch when /skavenger is the appropriate entry point

## Parallel Execution
- SHOULD launch independent agents in parallel (single message, multiple tool calls)
- NEVER run agents sequentially when their inputs are independent

### Orchestration Patterns (11 commands)

Three modes: **Parallel-then-Sequential** (`/chekpoint` reviewers → kody consolidate → gate; `/skanner` arkonte+kartograf → report), **Sequential** (`/abra-kdabra` arkitect→konstruct→feniks; `/medik` checks→mekanik+kurator→gate→repair→verify; `/doks`; `/evolve`), and **Direct** no-agent (`/nexus`, `/kompact`, `/almanak`, `/skavenger`, `/forge`). Full per-command flow diagrams — see **`agent-authoring` skill**.

## Approval Criteria
- CRITICAL → BLOCK merge, fix immediately
- HIGH → WARN, should fix before merge
- MEDIUM/LOW → NOTE, optional
- **Consolidator boundary**: kody (Phase 2b of `/chekpoint`) MAY consolidate duplicate BLOCKs and MAY escalate severity, but MUST **never downgrade an upstream BLOCK** from any Phase 2a specialist (typescript-reviewer, python-reviewer, spektr, orakle). If kody disagrees with a specialist BLOCK, it reports the BLOCK as-is and appends its dissent as a separate NOTE. The `/chekpoint` Phase 3 gate runs a dual check (raw Phase 2a BLOCKs AND kody-consolidated BLOCKs) so any silent drop is detected mechanically. See `.claude/agents/kody.md` → "Upstream BLOCK Preservation".

## Communication
- Agents return structured output (markdown with sections)
- MUST include severity levels in reviews (BLOCK/WARN/NOTE or CRITICAL/HIGH/MEDIUM/LOW)
- NEVER let an agent modify code without explicit approval from the user

## Command-Level Skills (no agent owner by design)

Some skills are loaded directly by commands because the work is deterministic and indirection through an agent adds no value. These are **not** routing bugs — doks and audit tools treat them as intentional. Current command-level skills: `verification-loop` (loaded by `/chekpoint` Phase 1), `strategic-compact` (loaded by `/kompact`), `skill-creator:skill-creator` plugin (loaded by `/evolve` step 6 Generate for PROMOTE proposals only — keeps the analysis agent pure and centralizes collision handling at command level), `council` (loaded by `/abra-kdabra` Step 1.5 + main orchestrator ad-hoc — anti-anchoring via sibling sub-agents). Full rationale per skill (why no agent owner, history, contract) — see **`agent-authoring` skill**. When adding new command-level skills, document the rationale in that skill's table.

### Skill capability declaration — `requires_tools:` frontmatter

Skills that invoke sub-agents (`Task`), `WebFetch`, or tools outside their owner agent's default grant SHOULD declare `requires_tools:` in frontmatter as a YAML list. The capability-alignment check (run via `/medik`) verifies alignment against the owner agent's `tools:` field. Full pattern (YAML example, FAIL/WARN severity rules, heuristic fallback, seed adopters) — see **`agent-authoring` skill**.

## Agent Template Contract

Every new agent file MUST derive from the canonical skeleton at `.claude/agents/_TEMPLATE.md.example`. Mandatory sections (frontmatter + identity paragraph + `## Output Format` + `## Memory`), strongly recommended sections (`## Expertise`, `## Workflow`, `## no_context Rule`), optional sections by use case, K-first naming convention, opus-vs-sonnet model decision tree, anti-patterns flagged by kody and the agent frontmatter linter — full reference in the **`agent-authoring` skill** (loads on-demand when creating, editing, or reviewing an agent). Enforcement: agent frontmatter linter (mechanical, run via `/medik`) + kody review during `/chekpoint`.