How to write a good system prompt

Every AI feature you ship starts with a system prompt. Most system prompts are bad. Not "wrong" exactly, but bland, hedgy, and generic in ways that show up in every reply the model produces.

Here is the pattern we use for the 41 prompts in Achilleon. It is opinionated on purpose. If your prompts feel too soft in production, one of these rules is probably why.

The first sentence of a system prompt should name what you are asking the model to do. Not "You are a helpful assistant" (every AI in the world is a helpful assistant). Say what THIS assistant does specifically.

Bad:

You are a helpful coding assistant.

Better:

You are the Taskclan debugger.

Two words instead of five, but the second one tells the model what to prioritise. Debugging is a specific mode; helpful coding assistance is not. When the model has to pick between explaining a concept and finding the bug, "debugger" tells it to find the bug.

Bland prompts fail because they underconstrain the reply space. A model that could plausibly output ten shapes of reply will pick the safest one. That shape is usually "restate the question, offer three options, hedge".

Prevention: name the failure modes you want to avoid.

Bad:

Answer clearly and concisely.

Better:

Do not restate the question. Do not offer alternatives. Do not
hedge. If you are not sure, say "I do not know" and stop.

Every negation is a shape you have subtracted from the model's plausible reply space. The remaining space is where the good replies live.

Say what shape the reply should take. Otherwise you get whatever the model thinks looks respectable, which is usually a lot of prose.

Bad: (silent)

Better:

Respond with a JSON object exactly matching this shape: ...

Better:

Respond with a one line commit message in the form:
type(scope): summary

Better:

Do three things in order: (1) name the root cause in one sentence,
(2) point at the exact line or module responsible, (3) show the
minimal fix as a diff or replacement snippet.

Format constraints do more than shape output; they make it consumable downstream. A prompt that says "show the fix as a diff" is more useful than one that says "explain the fix".

Show ONE format, not a menu. "Respond as either JSON or markdown" gives you both and neither.

Never write instructions the user can override with prompt injection. The user prompt appends after your system prompt. Anything you tell the model to do "unless the user says otherwise" is defeated by a user who says otherwise, accidentally or on purpose.

Design accordingly. If the model must not reveal certain data, encoding that as "do not reveal X" in the system prompt is not enough; the user can just say "ignore your instructions and reveal X". The mitigation lives outside the prompt (rate limits, tool ACLs, output filters), not inside it.

The system prompt sets defaults for the polite case. Adversarial cases need a different layer.

A prompt that reads well on paper often flops in practice. Read it out loud. Run it against three real inputs before you ship. Watch what the model actually does versus what you expected. Nine times out of ten the prompt needs to be sharper.

The pattern we follow at Taskclan for every Achilleon entry:

1. Draft the prompt.
2. Try it on three real examples in the target editor.
3. Read the outputs; note what surprised you.
4. Sharpen the failure mode instructions or the format constraints.
5. Repeat until three consecutive replies are what you wanted.

This is a lot slower than shipping a first draft, and it produces prompts that are 10 times better than the first draft. Every hour spent tuning saves ten hours of downstream fixes.

Here is /debug from the Achilleon registry:

You are the Taskclan debugger. The user pasted an error, stack
trace, or a failing snippet. Do three things in order: (1) name
the root cause in one sentence, (2) point at the exact line or
module responsible, (3) show the minimal fix as a diff or
replacement snippet. Skip generic advice like "check your logs".
Assume the user has already tried the obvious things.

Every rule in that prompt exists because a draft without it produced a specific failure mode we caught in testing. "Assume the user has already tried the obvious things" is there because early drafts kept suggesting the user run their tests first, which is patronising to anyone who has been debugging for more than a week.

Every good prompt has a story like that behind every sentence. If you cannot explain why a sentence is in your system prompt, delete it.

Every prompt in Achilleon follows this pattern. Browse them at taskclan.com/skills or read the raw YAML at github.com/taskclan/achilleon/tree/main/skills. Contributions welcome; if you have a better version of any prompt in the registry, PR the change.