RU
Get in touch
Chapter 10

Choose Prompt, Instruction, Skill, Hook, or CI by Guarantee

Prompt, instruction, skill, hook, and CI are not five styles of one text. They engage at different times and give a different level of guarantee. The right choice shrinks context and doesn't create a false sense of control.

Surface · Fits · Guarantee

  • Prompt - A one-off goal and local context; The model's decision in the current task
  • Project instruction - Short persistent repository rules; Persistent context, but not enforcement
  • Skill - A repeatable multi-step workflow; A reusable procedure the agent executes
  • Hook - A deterministic action on an agent-loop event; Script execution by the specific host's rules
  • CI - An objective merge or release gate; A server-side check independent of the agent

The difference is fundamental. A prompt affects only the current task. A project instruction gives persistent context but not enforcement. A skill is a reusable procedure the agent executes. A hook is a deterministic action on a loop event. CI is a server-side check independent of the agent. In the companion project this choice is a plain deterministic router.

TypeScript
export type GuidanceSurface = "prompt" | "project-instructions" | "skill" | "hook" | "ci";

export interface GuidanceQuestion {
  readonly repeats: boolean;
  readonly isWorkflow: boolean;
  readonly mustBeDeterministic: boolean;
  readonly isObjectiveMergeGate: boolean;
}

export function chooseGuidanceSurface(question: GuidanceQuestion): GuidanceSurface {
  if (question.isObjectiveMergeGate) {
    return "ci";
  }
  if (question.mustBeDeterministic) {
    return "hook";
  }
  if (question.isWorkflow) {
    return "skill";
  }
  if (question.repeats) {
    return "project-instructions";
  }
  return "prompt";
}

To run your own situation through the router and see the recommended surface, use the lab.

Interactive lab 3

Choose the surface

Prompt: a one-off goal, context, scope, and Done when.

On examples the routing becomes obvious: "fix exactly this defect" goes to a prompt; "always run npm run check" can be stated in an instruction, but the real obligation comes from CI; "run the release review in seven steps" becomes a skill; "block changes to migrations" needs a permission or hook, not a stronger adjective; "don't merge on a red test" belongs to branch protection.

A guarantee is not the loudness of the wording. Moving a requirement to a stronger surface (from prompt to hook, from instruction to CI) changes not the tone but the mechanism: from "the model will probably account for it" to "the system won't let it through."

The subtlest of the five surfaces is the hook. It's easy to turn into a second opaque agent, so it gets its own chapter.

Knowledge check

Which surface gives an objective merge guarantee independent of the agent?

Links