| name | define-tool |
| description | Meta-skill — scaffold a new tool integration (CLI binary, MCP server, or HTTP API) so Claude can use it. Installs it, writes a tool reference, updates the tool note at config/tools/<slug>.md (flips connected:true on smoke-test pass), and links it from the operator profile. |
/define-tool
Tools are how Claude reaches outside the vault. Defining a tool installs it (when possible), documents it, and wires it into the system.
Operates under [[type-scaffolding]] — design every required field, section, and structure deliberately. A type definition is a contract, not a folder layout. Apply the senior-teammate cold-pickup test, mark required vs optional explicitly, and validate by walking a real instance before locking the schema.
Detection clause
Surface proactively when:
- A workflow has failed ≥2 times in 14 days because of missing capability ("I can't read your Slack" recurring)
- The operator pastes data manually that a tool could fetch (calendar events, emails, transcripts)
Ask: "You've pasted {data type} from {source} a few times this week. Want to wire it up so I can fetch it directly?"
JTBD-first interview
- What tool? Name + purpose — the capability gap it fills.
- How does Claude reach it? CLI binary, MCP server, or HTTP API.
- Authentication? API key (where? always
.env), OAuth, none.
- Common commands? 5-10 most-used invocations with examples.
- Limitations? What it can't do, what fails silently, what's flaky.
- Detection clause — when should Claude propose using this tool proactively?
Install
Pick install method based on tool type:
- CLI — Run install command (Homebrew, npm, pip, curl). Verify with
which {binary}.
- MCP — Add entry to
.mcp.json at vault root. Operator restarts Claude Code to load.
- API — Add key to
.env (operator pastes; never commit). Confirm .gitignore includes .env.
If install fails, document the manual steps and surface to operator.
Seed the tool note (pre-verification)
If config/tools/<slug>.md doesn't already exist (operator may have named the tool in onboarding, in which case it's seeded), create it now with connected: false:
---
tool: {Tool Name}
slug: {kebab-slug}
category: {comms | meetings | crm | ...}
class: operator-named
connected: false
added-on: {today}
connector: unknown
---
The note's body has stub ## What it is, ## Best practices, ## Connection notes, ## Linked use cases sections. This tracks the tool exists even if smoke verification fails.
Verify
Run a smoke test command appropriate to the tool. On pass, continue to scaffold. On fail, append to the tool note's ## Connection notes what failed (one short paragraph), leave connected: false, and stop — do not write the tool reference doc. The operator can retry via /define-tool <name> later.
Scaffold the reference (only on smoke pass)
Create config/rules/tools/{name}.md (the tool reference doc — usage, commands, limitations):
# {Tool Name} — Tool Reference
{One-paragraph description and when to use}
## Access Method
{CLI binary path / MCP server name / API base URL}
## Common Commands
| Command | What it does | Example |
|---|---|---|
| ... | ... | ... |
## Known Limitations
- ...
## Common Mistakes
- ...
## Authentication
{None / API key in .env / OAuth flow}
## Detection clause
{When Claude should propose using this tool proactively}
Flip the tool note connected
After the reference is written:
- Flip
connected: true on config/tools/<slug>.md frontmatter
- Fill in
## Connection notes with how Claude reaches it (CLI path, MCP server name, env var name)
- Link the tool note from the operator profile's
## Tools in use section if not already linked
The PostToolUse hook fires declaration-changed on the reference write — install is now logged.
What NOT to do
- Don't commit secrets.
.env only, .gitignore enforced.
- Don't write a tool reference for a tool that isn't installed and verified. Untested docs lie.
- Don't define a tool that overlaps an existing one — check
config/rules/tools/ and config/tools/ first.
- Don't skip the detection clause. A tool nobody knows when to use is dead weight.
- Don't flip
connected: true on the tool note before the smoke test passes. The connection state is the system's truth about whether Claude can actually reach the tool.
