Writing Agent Prompts for Claude Code

Source-verified Feb 2026. Every rule has a citation or observed failure mode. Not trained assumptions.

Sources: Anthropic Claude Code docs, Anthropic agent skills best practices, morphllm.com Claude Code best practices, github.com/shanraisshan/claude-code-best-practice, empirical Flonest monorepo sessions Feb 2026.

What Claude Code actually is right now (Feb 2026)

The non-obvious things (what most people don't know)

ultrathink is a trigger word, not a prompt. Put it anywhere in your SKILL.md body to force extended thinking for that skill's tasks. Use it for migrations, RPC design, security decisions — not for simple CRUD.

!command injects live data before Claude sees the prompt:

---
name: pr-summary
description: Summarize a pull request
context: fork
agent: Explore
---
## Live context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`

Summarize this PR.

Claude receives the rendered output, not the command. Use this to inject current DB schema, current migration list, or current file contents into a skill automatically.

Skills do NOT reliably auto-invoke. Anthropic says they should. Real usage says: often they don't for simple tasks. Mitigation: make your skill description very explicit and "pushy" (see description section below). For critical workflows, add a slash command alias alongside the skill.

Core prompt rules

1. Anchor before acting — always

Read memory/DECISIONS.md and <exact-file-path> before writing anything.

Claude Code loads skill metadata at startup but reads files only when triggered. Without anchoring, it writes from training knowledge, not your actual codebase. Observed failure: migration written without reading schema → duplicate columns created.

2. One task per prompt. Two tasks = explicit sequence.

Two tasks. Do them in order. Do not start Task 2 until Task 1 is complete.

TASK 1: ...
TASK 2: ...

Claude will parallelize if not blocked. Observed failure: TypeScript types generated before schema migration confirmed → type drift.

3. Explicit DO NOTs block "helpful drift"

Do NOT touch any existing tables.
Do NOT generate TypeScript yet.
Do NOT run the dev server.
Do NOT edit the original RPC — extend it in a new migration.

Claude is trained to be helpful. It will do adjacent useful things unless blocked.

4. Match freedom to task fragility

Source: Anthropic skill authoring docs (verified Feb 2026). Wrong: giving high freedom to a migration. Wrong: giving low freedom to a UI component.

5. Schema first. TypeScript after schema is confirmed.

Migration only. Do NOT generate TypeScript. 
After migration is done, I will confirm, then we do TypeScript.

Observed failure: TypeScript generated from stale schema across 3 Flonest sessions. Painful to unwind.

6. Require idempotency on all SQL

Idempotent: IF NOT EXISTS everywhere.
DROP POLICY IF EXISTS before CREATE POLICY.

Observed failure: 18/65 Flonest migrations were fix-migrations from non-idempotent originals. That's 28% rework from one missing requirement.

7. If corrected more than twice → /clear and restart

Verified community pattern (morphllm.com, 2026): "A clean session with a better prompt almost always outperforms a long session with accumulated corrections." Re-anchor with the files you need, fix the original prompt, start clean.

8. Verify before done

Run tsc --noEmit and confirm zero type errors before marking complete.

Or for SQL:

Confirm the migration file is valid SQL before committing.

CLAUDE.md — structure rules (verified)

• Hard limit: ~150 lines. Beyond this, rules get lost. Ruthlessly prune.
• Delete rules Claude follows without prompting — they waste tokens.
• Move detailed guidance to /rules/*.md — modular, path-scoped rules system.
• Move knowledge to memory/ files — reference them from CLAUDE.md, don't inline.

# CLAUDE.md — keep this ≤150 lines
## Critical
- Read memory/DECISIONS.md before any DB change
- Read memory/CONTEXT.md at session start

## Rules
See .claude/rules/ for topic-specific rules.

Skill description — how to write it (source: Anthropic docs)

• Write in third person — injected into system prompt. Inconsistent POV breaks discovery.
• Be pushy — Claude undertriggers skills. Say "ALWAYS use when", not "use when".
• Include trigger phrases — Claude uses these for selection, no classifier, pure LLM reasoning.
• Max 1024 characters.
• Name must be gerund form: writing-agent-prompts, not agent-prompt-writer.

Bad (passive):

"Patterns for writing prompts for Claude Code"

Good (pushy):

"ALWAYS use this skill when writing a task for Claude Code, crafting an agent instruction, or debugging why Claude drifted. Trigger on: 'prompt for claude', 'tell claude to', 'how do I ask claude'."

Failure modes — reference table

For reference: !command and context: fork patterns

Read references/advanced-patterns.md when you need:

• Dynamic context injection (!command) into skills
• Subagent skills (context: fork)
• Multi-agent orchestration patterns
• ultrathink placement for extended thinking tasks