grimaldost 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:
# 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 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:
- 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. - Reference slash commands in the Definition of Done, e.g.:
- [ ] `/<review-command>` returns an APPROVE verdict - [ ] `/<gate-command>` reports no blocking failures - 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.
- Reference schemas, configs, and templates by name when a reference skill resolves them — name the artifact, let the skill supply the content.
- 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.