Toolkit Awareness

---
name: toolkit-awareness
description: Know what skills, agents, commands, and hooks are installed in the current Claude Code environment, and reference them well in prompts and specs. Use when answering "what tools/agents/commands/hooks do I have" (including narrower inventory questions like which hooks are configured), determining which installed skill owns or is responsible for a given concern — a scoring rubric, a schema, project conventions — so you point at the owner instead of duplicating it, planning work that will run in Claude Code, or writing a task spec or definition-of-done that should reference slash commands or quality gates. Produces a live inventory via a scan script rather than relying on a hand-maintained list.
---

# Toolkit Awareness

Two jobs: get a **live** picture of what's installed, and reference it well in
prompts and specs. The inventory is generated on demand — nothing
hand-maintained to drift.

## Get the live inventory

Run the scan script; it enumerates skills, commands, agents, and hooks from
user-level (`~/.claude`) and project-level (`<repo>/.claude`) configuration:

```bash
# A skill runs with cwd = the user's project, not the skill dir — use the absolute path.
uv run --no-project -- python "${CLAUDE_PLUGIN_ROOT}/skills/toolkit-awareness/scripts/scan_toolkit.py"          # grouped table
uv run --no-project -- python "${CLAUDE_PLUGIN_ROOT}/skills/toolkit-awareness/scripts/scan_toolkit.py" --json   # machine-readable
```

The scan also lists **plugin-provided** components via `claude plugin list`
(they live in the plugin cache, not `.claude/`). Without the CLI (another
harness), it still reports the `.claude/` tree and flags plugins as not
enumerated — fall back to a repo's generated `AGENTS.md` index when one
exists, else a directory scan of its `plugins/*/skills/`.

Prefer the scan over memory: a remembered list is wrong the moment something
changes.

**When a tool answers differently than it did a moment ago**, the cause is
usually where it was invoked from, not what it was asked:
[`references/environment-traps.md`](references/environment-traps.md) lists the
recurring ones and the signature that identifies each fast.

`--check-serving <transcript_path>` diffs the hook commands recorded in a
session transcript against every installed `hooks.json` and warns on a mismatch
— the signature of an app-level **frozen plugin snapshot**, where every disk
layer reads "current" but the running session is weeks behind; verify headless
(`claude -p`). It always exits 0. This is an on-demand call: the SessionStart
inject that used to carry it was retired, because the harness already places
skill names and descriptions in the system prompt.

## How to reference the toolkit in prompts and specs

When writing a task prompt or a definition-of-done that another agent session
will execute, lean on what's installed instead of restating it:

1. **Don't restate conventions a skill already handles.** Write "follow the
   invariants in `<conventions skill / GUARDRAILS path>`" rather than copying the
   rules. Convention skills fill in the detail automatically.
2. **Reference slash commands in the Definition of Done**, e.g.:
   ```markdown
   - [ ] `/<review-command>` returns an APPROVE verdict
   - [ ] `/<gate-command>` reports no blocking failures
   ```
3. **Don't tell a prompt to "use agent X".** Claude Code delegates to subagents
   automatically; agents are invisible to task prompts and naming one is noise.
4. **Reference schemas, configs, and templates by name** when a reference skill
   resolves them — name the artifact, let the skill supply the content.
5. **Name the quality gates, not their internals.** "Pass the pre-commit and
   type-check gates" is portable; pasting the gate config into the prompt is not.

## When multiple skills could apply

Know which skill *owns* what and reference the owner instead of inlining a
stale copy — one skill owns a scoring rubric, another project conventions,
another a schema. The scan's descriptions are the fastest way to see who owns
what.

## Source of truth

Skills are condensed copies of authoritative docs; on conflict the doc
(CLAUDE.md, a guardrails file, a schema doc) wins — update the skill. The
inventory says *what exists*; the docs stay the truth for *what's correct*.