Skip to main content

From utterance to skill launch

From here, using a single bug as the subject, we follow the flow of /debug. This is the subject we use throughout the guide.

Today's bug

The user-fetching function fetchUser returns undefined when the target is not found, and the caller crashes. A report came in: "the screen sometimes goes blank."

A developer types this in.

fetchUser returns undefined for an empty array and crashes. Fix it

The moment this one line is sent, the harness begins to move.

First, the UserPromptSubmit hook runs​

Before the utterance reaches the model, the UserPromptSubmit event's hooks always run. In this environment, two are registered—promote-ultracode.sh and surface-salvage-on-resume.sh (registration is in settings.json; for details, see How hooks work). The latter is a hook that, when resuming a session interrupted by something like a rate limit, injects—just once—a notice that lets you notice saved investigation results, so it does nothing for this utterance.

The protagonist is promote-ultracode.sh (🔧 author's own). This hook checks whether the utterance contains a compound phrase indicating a heavy task, such as "across multiple files," "large-scale refactor," or "exhaustively." If it does, it slips a notice into the context: "how about switching to ultracode (high output + workflow)?" Because the failure of taking a heavy task as a one-off and failing to turn it into a workflow was repeated, it became a mechanism that nudges at the utterance stage.

promote-ultracode.sh (excerpt)
ULTRACODE_TRIGGER='複数ファイル|横断的|...|大規模(リファクタ|変更|改修|移行|刷新)|...'

if ! echo "$PROMPT" | grep -qiE "$ULTRACODE_TRIGGER"; then
  # No heavy-task trigger word → pass through without injecting
  exit 0
fi

This time, the utterance "fix one function" is a one-off task, so it does not hit the trigger. The hook passes through doing nothing. This is an example of a Computational Guide in Guides and Sensors terms (a mechanism that runs deterministically before an action and sets its direction). Quietly letting it pass when it does not hit is also part of the job.

Next, the skill is chosen​

When the utterance reaches the model, it judges "which skill's turn is this?" /debug has two launch entrances.

  • Utterance trigger: an utterance containing words like "bug," "error," "doesn't work," "failed"
  • Explicit call: type /debug directly

The description in the skill's frontmatter is shown to the model in advance, as the skill list. This time it is "it crashes. Fix it," so on that basis it is judged a debugging request and /debug is chosen. The skill's utterance-trigger mechanism and the SKILL.md spec (fields like allowed-tools / effort) are Claude Code standard (📦); the /debug procedure itself is the author's own (🔧).

~/.claude/skills/debug/SKILL.md (frontmatter)
name: debug
description: Investigate and fix the cause of bugs / errors / test failures (autonomously resolve via Investigate→Fix→Verify in up to 3 iterations). ...
allowed-tools: Read, Grep, Glob, Bash, Write, Edit, WebSearch, mcp__context7__..., mcp__sequential-thinking__...
effort: max

Two elements are at work here.

  • allowed-tools: a specification that lets you use the listed tools without a permission prompt during this skill's work (it is not a mechanism that restricts the tool's usage scope; the restricting side is disallowed-tools). Because /debug handles not only investigation but also fixing, it lists Write / Edit. The difference from /review, which as a norm sticks strictly to read-only, shows up here
  • effort: max: to prepare for verifying multiple hypotheses that require a lot of thinking, while this skill is active it overrides the session effort level and runs at the maximum (above low / medium / high / xhigh)

And once launch is decided, the body of SKILL.md is loaded and becomes the work procedure as is. For /debug, it is a structured workflow: "iterate Investigate → Fix → Verify up to 3 times."

The workflow of SKILL.md (excerpt)
1. Step 0 (MCP launch): forced use of sequential-thinking + context7
2. Step 0.5 (Spec-First): check whether spec drift is the root cause
3. Classify the error (type / logic / environment / concurrency) → narrow down the starting point
4. Form hypotheses (prioritize by score × cost, parallel verification forbidden)
5. Verify → pin down the true cause → propose a fix → Verify (pass 1)
6. Iterate (new hypothesis, up to 3 passes)

The flow so far​

Choosing between the /debug skill and the debugger subagent

This time, we use the /debug skill to fix it right in the environment that is open now. If you want to isolate a large amount of code into a separate context and investigate at length, you delegate to the debugger subagent. The names are similar, but /debug is for immediate response and debugger is for isolated investigation—a division of roles.

Summary of this chapter

The key points:

  • Before the utterance reaches the model, the UserPromptSubmit hook always runs (passing quietly if it does not hit)
  • A skill is chosen by an utterance trigger or /name, and SKILL.md's frontmatter and body become "the constraints and procedure of the work"
  • effort: max boosts reasoning, and allowed-tools decides which tools are usable without a permission prompt

Next, in On-demand MCP loading, we look at /debug's first move, "Step 0."