Using Skills

What this skill carries — grep references/ for any subject the names below miss: !d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"

Route before you act. Before the first tool call of a turn, decide which of these owns the task. The main thread's job is routing, not doing.

The routing table

Read top to bottom; the first row that matches wins.

The task is	Route to	How
already-invoked skill (<command-name>/dev</command-name> in this turn)	it is already loaded	just follow it — never re-invoke
the prompt opens Implement the following plan: and the plan's frontmatter has workflow: <name>	that skill	Skill(skill="workflows:<name>") (as written when plugin-qualified) FIRST — the context was cleared at approval; never craft, never inline
anything "in a new / background / separate / companion session"	agent-spawn skill	it is the transport; the real task goes inside its prompt
a feature, bug fix, or engineering change	/dev	Skill(skill="dev")
data: build/merge/model/profile a dataset, a table, a figure, a number	/ds	Skill(skill="ds")
long-form prose a human reads: article, memo, brief, chapter	/writing	Skill(skill="writing")
a Typst talk built from a research paper	/workshop	Skill(skill="workshop")
lecture notes / slides for a course chapter	/notes, /slides	teaching plugin
substantial work with no domain gate, but worth doing properly	/craft	Skill(skill="workflows:craft")
a specialist's job with no workflow shape	farm out to the agent	see the Iron Law below
a substantive question, or any search for sources	your own library FIRST	see the Iron Law below — not WebSearch
image, PDF, video, audio — understanding its content	look-at	never the Read tool
creating or substantially editing a skill / workflow / plugin	workflows:skill-creator, workflows:workflow-creator, workflows:plugin-creator	never the built-in creators
setting a /goal, or briefing a session that will outlive your attention	hound	Skill(skill="workflows:hound")
a lookup, a one-line answer, a typo fix, conversation	do it inline	no ceremony

A domain workflow beats /craft when the task has its shape — it brings a gate craft does not have. /craft is not a universal wrapper.

Any code reading, "quick check", or "let me gather context" before invoking the matching workflow is a violation. Scope ("just one file", "simple question") does not exempt you.

IRON LAW: Delegate to the specialist by default

The persona agents exist so the main thread does not do their work. Doing it inline throws away their preloaded constraints and their deliberately narrow toolset, and spends main-thread context on file dumps a subagent would have absorbed.

The job is	Agent
build / merge / model / profile data	ds — grading work that exists → ds-reviewer
slides, lecture notes, exams, syllabus	teaching — read-only checks → slide-auditor, notes-auditor
a talk built from a paper	workshop — grading a built deck → workshop-reviewer
memo, article, chapter, comment letter	writing / writing-legal / writing-econ — grading → writing-reviewer
the user's mail; their calendar, notes, tasks, chats	email; assistant
the user's own library or the literature	librarian
several independent searches or sweeps	one --tasks row each — rows run in parallel

Delegate through the workflows:farm-out skill, which supersedes the Agent and Workflow tools:

S="${CLAUDE_PLUGIN_ROOT}/skills/farm-out/scripts"
jq -n '[{prompt:"…", expect:"/abs/out.md", label:"…", agent:"ds"}]' > /tmp/t.json
bash $S/farm.sh --tasks /tmp/t.json --cwd /repo

Omit "agent" on a row that must itself plan, fan out, or run a craft skill — persona agents are sealed and hold no Agent/Skill/Workflow. Read the farm-out skill before your first call in a session; a returned summary is never evidence, so always pass --expect.

~/.claude/hooks/main-thread-guard.sh enforces the routing once you have chosen to delegate; it cannot make the choice for you. That choice is this rule. Stay inline only for trivial, conversational, or already-verified work — "the user did not ask me to delegate" is not a reason, because this rule is the asking.

IRON LAW: Search what the user already has before searching the web

WebSearch/WebFetch is the LAST resort for a substantive question, not the first move. The user has read, saved and written more on their own subjects than an open-web sweep will surface, and their own material is more current and more specific than your weights.

Order, and stop at the first that answers:

1. The wiki — ~490 concept/QA articles plus ~880 case notes in ~/notes, covering con law, corporations, civ pro, contracts, evidence, tax, securities, corporate governance and finance/econ. Try zvec_grep_search with root: /home/eh/notes first — sub-second and good on paraphrase, but only when that MCP tool is in your toolset (persona agents do not have it) and its daemon is up. Otherwise qmd query "<question>" -n 10 then qmd get "#docid": global index, works from any directory and any agent with Bash. Answer from the note and cite it by path.
2. librarian — the user's curated library and the academic literature: NotebookLM, Readwise/Reader highlights and saved articles, Google Scholar, Google Drive. Farm it out; main chat NEVER calls the readwise CLI directly.
3. The open web — WebSearch, WebFetch, or the deep-research skill for a synthesized multi-source report.

Answering a domain question from training data alone, without step 1, is the failure this rule exists to prevent — you will sound confident and miss what the user actually thinks.

Exempt: anything whose answer changes daily or lives only online — current model ids and API docs (always verify live, your training data is stale), prices, releases, news, a named URL the user handed you, and library/tool documentation.

IRON LAW: Session transport priority

Session keywords — 'new session', 'separate session', 'background session', 'parallel session', 'companion session', 'spawn an agent', 'kick off claude in ', 'hand off to a session' — mean the agent-spawn skill is invoked FIRST, whatever else the request mentions. It launches the session; the task goes inside its prompt. (agent-msg delivers to a session that already exists.)

"use workflows:skill-creator in a new session" → invoke agent-spawn, put "use workflows:skill-creator" in the prompt. Doing the task directly runs it in this context, where it dies with the conversation and the user cannot revisit or monitor it. Agent(run_in_background) is not a spawned session for the same reason.

IRON LAW: Media goes through look-at

Never pass an image, PDF, video, or audio path to Read. Read on an image costs 1,000+ context tokens; look-at returns 50–200 tokens of extracted content. File size is irrelevant — content type decides. look-at is for you, not the user; it applies whether or not they asked.

Bash(
  command='"${CLAUDE_PLUGIN_ROOT}/skills/look-at/scripts/look_at.sh" --file "/abs/path.pdf" --goal "Extract the executive summary"',
  description="look-at: extract executive summary"
)

Use Read for source code, text, and config — anything needing exact bytes for editing. If a look-at extraction is insufficient, escalate to Read.

IRON LAW: Follow a loaded skill exactly

When a skill loads, follow its patterns, required parameters, and step sequence as written. Simplifying a skill's required pattern discards the reason it was loaded.

Red flags — STOP

About to	Do instead
Invoke a skill the user already invoked this turn	check for <command-name>; it is loaded — proceed
Read code to "understand the bug" before /dev	invoke /dev first; that reading IS the investigation
Do a specialist's work inline because it "looks quick"	farm it out — the toolset restriction is the point
Call Agent or Workflow directly	farm.sh (the guard hook will deny it anyway)
Pass a .png/.pdf to Read	look-at
WebSearch a question in the user's own domains	search the wiki first, then librarian
Answer a law/finance question straight from training data	the wiki holds the user's own view — check it
Call the readwise CLI from main chat	farm out to librarian
Invoke skill-creator:skill-creator or plugin-dev:* directly	the workflows: wrapper — the built-ins have no validation hooks
Do "X in a new/background session" directly or via Agent	agent-spawn is the transport; X goes in its prompt
Relay a delegated agent's summary you did not verify	check the --expect artifact yourself

Deeper reference

references/agent-harnessing.md — background/parallel execution, tool restrictions, delegation templates, failure recovery, cost classification.