writing-agent-instructions

name	writing-agent-instructions
description	How to write great agent instructions for an agent-native app or template: AGENTS.md, skills, and tool/action descriptions. Use when authoring or reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or deciding what belongs in instructions vs skills vs memory.
scope	dev
metadata	{"internal":true}

Writing Agent Instructions & Skills

This is a creator-facing guide. When you build an agent-native app or template, the agent's behavior is only as good as the instructions you give it. Three surfaces carry that guidance: AGENTS.md (the map), skills (the deep dives), and action/tool descriptions (how the agent picks the right tool). Write each one for fast retrieval, not for prose.

Keep AGENTS.md small and skimmable

AGENTS.md is loaded as orientation. It should be the smallest thing that lets the agent act correctly, with everything deep pushed into skills. Aim for these sections and little else:

• Purpose line — one sentence on what the app is and the primary workflow.
• Core rules — the handful of invariants that must always hold (data in SQL, operations go through actions, AI goes through the agent chat, schema changes are additive). Short, imperative bullets.
• Application-state keys — the navigation/selection/focus keys the agent reads to know what the user is looking at, with their shape.
• Action table — a compact table of action name -> purpose (see below).
• Skills index — a list of the skills that exist and when to read each one.

If a section is growing past a screen, it belongs in a skill. AGENTS.md answers "what is this app and what can I do," not "how exactly do I do the hard thing."

The 6,000-character cap is real and silent

A template AGENTS.md is injected into the runtime agent's system prompt and hard-sliced at COMPACT_PROMPT_RESOURCE_MAX_CHARS (6,000). Past that, the agent sees a truncation marker instead of your text, so the tail stops being always-on guidance and becomes something it has to go fetch. pnpm guard:agent-chat-context — the repository's own check — fails the build when a first-party file overflows; generated apps do not ship that repository-only guard. Keep files under ~5,500 so ordinary edits don't tip them over.

Two consequences worth designing around:

• Put the skills list second, right after the purpose line. It is the pointer to every deferred skill. If it lands in the truncated tail, the agent cannot discover any of the depth you carefully moved out.
• Markdown tables cost more than they look. Prettier pads table cells to align columns, and that invisible whitespace counts against the cap — enough padding in a wide action table to push a file back over it on its own. Both **/AGENTS.md and **/SKILL.md are in .prettierignore for this reason; keep them there and write table rows unpadded.

# Projects App

One workspace for projects, tasks, and notes. Agent and UI share the same SQL
data and the same actions.

## Core Rules

- Data lives in SQL via Drizzle. Use actions for all writes.
- All AI work goes through the agent chat; never call an LLM inline.
- Schema changes are additive only.

## Application State

- `navigation.view`: `home` | `project`
- `navigation.projectId`: selected project on a project page

## Actions

| Action           | Purpose                     |
| ---------------- | --------------------------- |
| `list-projects`  | List accessible projects    |
| `create-project` | Create a project            |
| `update-project` | Rename or archive a project |

## Skills

- `project-imports` — read before importing legacy CSV exports.
- `sharing` — read before exposing a project to other users.

Single-source AGENTS.md (CLAUDE.md is a symlink)

Keep one canonical instructions file: AGENTS.md. If a client expects CLAUDE.md, make it a symlink to AGENTS.md rather than a second copy. Two hand-maintained files drift, and the agent ends up with contradictory rules. One source of truth, linked where needed.

Keep generated guidance in sync

Framework guidance is authored once in this repo and copied outward. Treat .agents/skills/ as the canonical source for shared skills. Generated workspace skills in packages/core/src/templates/workspace-core/.agents/skills/ and first-party template copies of shared skills must stay byte-for-byte in sync; run pnpm sync:workspace-skills after editing a shared skill, and pnpm guard:workspace-skills before calling the guidance done.

Generated app and workspace instructions must teach the same action-first data contract:

• Normal app data goes through defineAction files in actions/.
• React calls actions with useActionQuery, useActionMutation, or callAction; route paths are a transport detail hidden behind helpers.
• Custom /api/* routes are only for route-shaped protocols such as uploads, streaming, webhooks, OAuth callbacks, public SEO/OG endpoints, or binary assets.
• Do not create pass-through routes whose main job is to call, repackage, or re-export an action.

Generated guidance must also distinguish deterministic tools from AI-shaped workflows. Provider reads, validation, deterministic transforms, CRUD, and persistence belong in focused actions. Research, analysis, generation, recommendation, synthesis, and other user-steerable multi-step work should start in the AgentSidebar and let the agent orchestrate those actions. State that sendToAgentChat({ openSidebar: true }) is the default handoff and that follow-ups stay in the same thread; do not add a second freeform prompt box.

Budget the first model request

Treat the initial prompt and tool catalog as a latency budget. The agent should start with a compact map of the app, then retrieve depth only when the task needs it.

• Set initialToolNames to the small set of actions used in the app's primary workflows. Keep tool-search available so every other registered action and connected MCP tool remains discoverable on demand.
• Keep essential, always-applicable rules in AGENTS.md. Put workflow detail in skills and long reference material in references/ or workspace resources that the agent can read when relevant.
• Do not inject full documents, transcripts, data dictionaries, source trees, or provider catalogs through systemPrompt or extraContext. Inject a bounded summary, stable ids/paths, and the exact action or resource lookup that retrieves the full content.
• Avoid duplicating action descriptions in prose. The starter tools already carry schemas; uncommon actions are available through tool-search.
• Keep view-screen concise. Return navigation, selection, visible summary, and ids needed for a follow-up read rather than full record bodies.

The goal is progressive disclosure, not reduced capability: a compact first request, precise discovery, and full fidelity once the agent knows which depth is relevant.

Say each thing once, in the layer that owns it

Current-generation models do not need a rule repeated in the system prompt, the instructions, and the tool description. Repetition is not reinforcement — it is three chances to disagree with each other, and the model spends effort reconciling them before it can act. Pick the owning layer:

Layer	Owns
System prompt / AGENTS.md	Which capabilities exist, and policy spanning tools: turn shape, what to do first, invariants that hold every turn
Tool / action description	How to call it, argument and result semantics, what to say about a result, when this tool rather than a sibling
Skill	Multi-step workflows, worked examples, field references, edge cases

The common mistake is restating a tool's mechanics as a numbered core rule. Deferred tools are loaded through tool-search, so the model always reads the description before it can call the tool — a start/update/complete sequence or an argument enum in the prompt buys nothing and is charged on every turn. State that the capability exists and when it applies; let the description carry how.

Prefer judgment over rules, and interfaces over examples

Blanket prohibitions were how older models were kept out of worst-case behavior. They now mostly cost accuracy, because a rule stated absolutely is wrong for some fraction of requests and the model has to guess which fraction it is in. Write the intent and let the model apply it:

• Say "match the surrounding code's comment density" rather than "never write comments." Say "response length mirrors the task" rather than "2–5 sentences."
• Skip arbitrary numeric formatting prescriptions (bullet counts, nesting bans) unless a surface genuinely breaks without them.
• Keep hard constraints for the areas where a wrong call is expensive and not self-correcting: security, destructive operations, fabricating data or success, and credential handling. Those stay absolute.
• Don't add few-shot examples of tool calls to teach usage. Examples narrow the model to the shapes you showed. Make the tool's own interface expressive instead — precise parameter names, enums that imply the state machine, .describe() on every field. Keep a literal example only where it defines a syntax the schema cannot, such as a pnpm action CLI invocation in dev mode.

When documenting version history, restore, or audit trails, use actions for full restorable snapshots (list-<resource>-versions, get-<resource>-version, restore-<resource>-version). Do not copy legacy raw-route version panels, such as document-version /api/* helpers, into new features. The Plans version-history pattern is the preferred model.

SKILL.md frontmatter must say what AND when

The description is the only thing the agent sees when deciding whether to read a skill. It must answer two questions: what the skill covers, and when to trigger it. A description that only describes the topic will not fire.

---
name: project-imports
description: >-
  How to import projects from the legacy CSV export. Use when the user uploads
  a project CSV or asks to migrate projects from the old system.
---

• Lead with the capability, then add an explicit "Use when…" clause.
• Be slightly pushy — over-triggering beats a skill that never loads.
• Keep it under ~40 words; it is loaded into context on every conversation.

Scope a skill to runtime vs dev

An optional scope field decides which agent loads the skill:

• both (default when omitted) — loaded by connected repo agents and the in-app runtime agent.
• runtime — loaded only by the in-app runtime agent.
• dev — for the human's coding agent (e.g. Claude Code) only. A scope: dev skill is invisible to the runtime agent everywhere (system-prompt skills block and docs-search).

Use scope: dev for internal-only guidance that should help connected repo agents such as Codex or Claude Code, but should not influence the deployed production agent. Do not use metadata.internal for this: it is catalog/package metadata and does not control runtime visibility.

---
name: release-checklist
description: >-
  Steps for cutting a release. Use when preparing or publishing a new version.
scope: dev
---

Omit scope for normal skills (the default both keeps them loading at runtime — fully backward compatible). For a dev-only skill, mark it scope: dev and optionally mirror it under .claude/skills/<name>/SKILL.md so Claude Code picks it up while the runtime agent skips it.

Progressive disclosure: lean SKILL.md, depth in references/

Write the SKILL.md as the lean, must-know layer: the rule, how to do it, the do/don't list, and pointers. Push long examples, exhaustive field references, API quirks, and edge-case tables into references/ files the agent reads only when it needs them.

.agents/skills/project-imports/
├── SKILL.md            # rule + happy path + do/don't
└── references/
    └── csv-format.md   # full column spec, encodings, edge cases

This keeps the always-loaded surface small and lets depth scale without bloating context. See the create-skill skill for the full skill format.

Write action-oriented tables

The agent scans tables faster than prose. Prefer a table of name -> purpose over paragraphs describing each operation. The same applies to state keys, field types, and any enumerable set. Tables are skimmable, diffable, and easy to keep in sync when you add an action.

Write clear tool/action descriptions

Action descriptions are tool descriptions — they drive tool selection. Make each one a precise, single-purpose sentence:

• Say what it does and what it returns, not how it's implemented.
• Describe each parameter in its .describe() so the agent fills it correctly.
• One responsibility per action. If a description needs "and also…", split it.
• Mark read-only actions (readOnly: true / http: { method: "GET" }) so the agent knows they're safe to call freely.
• For provider-backed shortcuts, make clear they are convenience paths, not capability ceilings. If arbitrary provider endpoints/filters may matter, point instructions to provider-api-catalog, provider-api-docs, and provider-api-request instead of implying the shortcut is all the agent can do.

defineAction({
  description: "Create a project. Returns the new project id and title.",
  schema: z.object({
    title: z.string().min(1).describe("Project title shown in the sidebar"),
  }),
  // ...
});

Bake in anti-fabrication and verify-before-done

App instructions should make honesty and verification the default behavior:

• Never fabricate. If data isn't found or an action fails, say so and recover — don't invent results or claim success. Read the real value via an action or query before reporting it.
• Verify before declaring done. After a change, confirm it with a read-back (re-query the row, re-read the screen via view-screen) instead of assuming the write worked.
• Recover, don't give up. On a recoverable error (a failed query, a transient fetch), retry or fix the input rather than abandoning the task. Keep this separate from the anti-fabrication rule — don't conflate "don't make things up" with "stop at the first error."

Put these as core rules in AGENTS.md so they apply to every turn.

Bake in secrets hygiene

Instruction authors must make credential handling explicit anywhere an app, skill, action, webhook, integration, or extension touches external services. Write the rule in terms of values, not just files: never hardcode real API keys, tokens, webhook URLs, signing secrets, OAuth refresh tokens, private Builder/internal data, or customer data in source, docs, tests, fixtures, prompts, screenshots, or generated content.

Examples may name credential keys such as OPENAI_API_KEY or SLACK_WEBHOOK, but values must be placeholders (<OPENAI_API_KEY>, ${keys.SLACK_WEBHOOK}) or clearly fake test data. Tell agents which approved channel to use instead: deployment env vars for deploy-level secrets, app_secrets / saveCredential / resolveCredential for scoped API keys, oauth_tokens for OAuth, and ${keys.NAME} substitution for extension/automation outbound HTTP.

What goes where

• AGENTS.md — applies to the whole app, every turn: purpose, core rules, state keys, action index, skills index.
• Skills — reusable how-to for a specific pattern, loaded on demand. Applies to everyone working in the app.
• Memory (memory/MEMORY.md) — per-user preferences and corrections, not authored guidance. See capture-learnings.

Do

• Keep AGENTS.md to roughly one screen of orientation; link out for depth.
• Update the action table and skills index whenever you add an action or skill.
• Write every SKILL.md description with an explicit "Use when…".
• Use tables for any enumerable set (actions, state keys, field types).

Don't

• Don't duplicate skill content inside AGENTS.md — point to the skill.
• Don't maintain two instruction files; symlink CLAUDE.md to AGENTS.md.
• Don't write vague descriptions ("helps with projects") — they won't trigger.
• Don't document niche/buried UI behaviors in instructions; let code and UI carry those.
• Don't paste real credentials, credential-looking dummy strings, private Builder/internal data, or customer data into examples. Use placeholders.

Related Skills

• create-skill — The skill format and templates this guide refers to.
• adding-a-feature — The four-area model (UI, actions, skills/instructions, application state) every feature must satisfy.
• actions — How action descriptions become agent tools.
• context-awareness — Application-state keys and the view-screen pattern.
• capture-learnings — Where per-user learnings go instead of AGENTS.md.