--- name: forge-agent-prompt description: Writing self-contained subagent briefs. Four-part structure (goal, context, constraints, return shape), token budgets, autonomy bounds, hand-the-question vs hand-the-command, anti-motivational filler. Contains ready-to-paste templates for investigation, implementation, and verification subagents. Use when an orchestrator agent needs to spawn a subagent and write its prompt. license: MIT --- # forge-agent-prompt You are writing a prompt that another agent (a subagent, a worker, a tool-use loop) will execute against a fresh context. The subagent has none of your conversation, none of your reasoning, none of your assumptions. Default-written subagent briefs are either too terse to be useful or so verbose they consume the budget they were meant to free. The contract: a brief is **self-contained, scoped, and ends with a clear return shape**. Read your own brief as if you had never seen the conversation. If you cannot do the task from the brief alone, the brief is broken. ## Quick reference (the things you must never ship) 1. A brief that starts with "Continue what we were doing." 2. No stated return shape (free-form output). 3. "Take your time" / "be thorough" / "do your best" - motivational filler. 4. Goal sentence containing "and" (compound task). 5. No length/effort cap on the return. 6. References to "the conversation above" or "previous messages." 7. A brief over 2000 tokens (you have not factored the task). 8. Prescribed step-by-step for an investigation (premise may be wrong). 9. The bare question for a lookup (just hand over the exact command). 10. No autonomy bound stated (read-only? can edit? can run shell?). ## Hard rules ### Structure **1. A brief has four parts, in order: goal, context, constraints, return shape.** Skip any part at your cost. The most common failure is skipping "return shape" - the parent then has to re-parse free-form output. **2. Open with the goal in one sentence.** "Find every place in src/ where we call the Stripe API directly without going through our billing wrapper." Not "investigate Stripe usage." **3. State why the work matters in one line.** "We are auditing for direct Stripe calls before a billing-provider migration." This is not decoration; it lets the subagent make judgment calls when the literal instruction is ambiguous. ### Context **4. Just enough background for the task. No more.** What you have already learned, what you have ruled out, what is known to be true. Anything beyond is filler. **5. Concrete artifacts beat abstract descriptions.** "Here are the three relevant files: src/billing.ts, src/checkout.ts, src/webhook.ts" beats "look in the billing area." Paths, function names, line numbers when you have them. **6. Past tense for what is done. Imperative for what to do.** "I have already checked X. Now: search Y." ### Constraints **7. State the autonomy boundary.** Read-only? Make edits? Run commands? Open PRs? Without this, the subagent over- or under-acts. ``` Autonomy: Read-only. Do not edit files. Do not run commands that mutate state. ``` ``` Autonomy: Edit src/billing/* only. Do not touch other directories. Do not run tests. ``` **8. State the time/effort budget.** "Spend at most 5 tool calls" or "respond in under 200 words." Without bounds, subagents over-explore. **9. State failure modes you want avoided.** "Do not propose architectural changes." "Do not rewrite the test file." Explicit don'ts are cheaper than waiting for the subagent to do the wrong thing and correcting it. **10. Hand over the question for investigations.** When the premise might be wrong, prescribed steps become dead weight. Trust the subagent to find the right path. **11. Hand over the exact command for lookups.** "Run `git log --since=last-week -- src/billing.ts`" is better than "find out what changed recently." ### Return shape **12. State the return shape in concrete terms.** ``` Return a JSON object with the shape: { "found": [{ "file": "src/billing.ts", "line": 42, "snippet": "stripe.charges.create(...)" }], "skipped": [{ "file": "src/legacy.ts", "reason": "vendored dependency" }], "notes": "..." } ``` OR ``` Return a markdown report with three sections: ## Findings ## Skipped (with reasons) ## Open Questions Under 300 words total. ``` **13. State the length cap.** "Under 200 words." "JSON only, no commentary." Without this, the subagent fills available space. **14. State what NOT to include in the return.** "Do not include your reasoning steps." "Do not summarize what you did." Subagent returns balloon to 2KB without these. ### Voice **15. Brief the subagent like a smart colleague who walked in cold.** Not like a junior employee. The subagent has the same baseline competence; it lacks only the conversation. Skip basics; include specific, surprising details. **16. No meta-commentary about the prompt itself.** "I want you to act as..." or "your role is..." waste tokens. State the work. **17. No motivational filler.** "Take your time," "be thorough," "do your best" - none change behavior. Cut. ### Tool guidance **18. Mention specific tools only if the choice matters.** "Use ripgrep, not find" matters when find would be too slow. "Use the Edit tool" usually does not. **19. State permissions positively when restrictive.** "Read-only. Do not run any command that mutates state." "Edits allowed only within src/billing/." ### When you have multiple subagents **20. Each brief is self-contained even if subagents will be merged later.** Do not write "see the other subagent's output for context." The other subagent has its own boundary. **21. Briefs to parallel subagents are structurally similar.** Fanning a search across 10 files? Brief differs only in the file path. Consistent structure makes the merge step easier. ## Common AI-output patterns to reject | Pattern | Why wrong | Fix | | --- | --- | --- | | "Continue from where we left off." | Subagent has no history | Self-contained brief with state | | "Take your time and be thorough." | No behavioral effect | Cut, state concrete cap instead | | "Do X. Also Y. And Z." | Compound task | Three subagents or three sequential steps | | "Investigate the auth flow." | No scope | Specific question, return shape, budget | | "Output your findings." | Free-form | Concrete shape (JSON or labeled markdown) | | "I want you to act as a senior engineer" | Role-play filler | Skip, state the work directly | | No autonomy bound | Subagent guesses | "Read-only" or "edit only X" | | "Use your best judgment" | Vague | Name the criteria explicitly | | References "the conversation above" | Broken across context | Inline the relevant fact | | 3000-token brief | Over-briefed | Refactor: less prose, more structure | ## Worked example: investigation brief (good) ``` Find every place in src/ where we read a JWT and verify which signing algorithm we accept. Why: We are tightening the JWT spec and need to know if any handler accepts 'alg: none' or 'alg: HS256' when we expect RS256. What I have already checked: - src/auth/middleware.ts uses jwt.verify with algorithms: ['RS256'] - src/lib/jwt.ts is a wrapper around jose; the algorithm parameter is passed through Autonomy: Read-only investigation. Do not edit files. Budget: Up to 6 tool calls. Respond in under 200 words plus the list. Return shape: JSON with shape: { "handlers": [ { "file": "...", "line": ..., "algorithm_check": "explicit" | "implicit" | "missing", "snippet": "..." } ], "open_questions": string[] } ``` What this demonstrates: one-sentence goal (rule 2); why explained (rule 3); what is already known stated (rule 4-5); explicit autonomy (rule 7); explicit budget (rule 8); concrete return shape (rule 12); length cap (rule 13). ## Worked example: implementation brief (good) ``` Add cursor-based pagination to listOrders in src/handlers/orders.ts. Why: Current offset-based pagination breaks under inserts and is slow at high page numbers. Spec: - Accept query params: cursor (opaque string), limit (default 50, max 200). - Return body: { data: Order[], next_cursor: string | null, has_more: boolean }. - Use keyset on (created_at DESC, id DESC). - See forge-api-design rule 10 for the pattern. Autonomy: Edit src/handlers/orders.ts only. Do not modify other files. Do not run tests. Budget: 1 attempt. Return the unified diff only. Return shape: A single unified diff with no prose before or after. Format: ```diff --- a/src/handlers/orders.ts +++ b/src/handlers/orders.ts @@ ... @@ ... patch ... ``` ``` ## Worked example: investigation brief (bad) ``` Look into the auth thing we talked about. See what you can find. Use your best judgment and let me know if anything jumps out. ``` Line by line: no concrete task; references "we talked about" (not in subagent context); "best judgment" with no criteria; "let me know" with no shape; nothing said about autonomy, budget, or return. ## Templates ### Investigation (read-only) ``` {one-sentence goal}. Why: {one-line motivation}. What I already know: - {fact 1} - {fact 2} Autonomy: Read-only. Do not edit files. Budget: Up to {N} tool calls. Respond in under {K} words plus the structured return. Return shape: {concrete JSON shape or labeled markdown sections} ``` ### Implementation (scoped edit) ``` {one-sentence goal}. Spec: - {requirement 1} - {requirement 2} - See {SKILL.md path} for the pattern. Autonomy: Edit {specific files / directory} only. Budget: 1 attempt. {Tests / typecheck / lint requirement, if any.} Return shape: A unified diff. No prose before or after. ``` ### Verification (judge / critic) ``` Review the diff below and decide whether it is safe to merge. Criteria: - {criterion 1} - {criterion 2} - {criterion 3} Autonomy: Read-only. Comment, do not modify. Budget: 200 words total. Return shape: { "verdict": "approve" | "block" | "approve_with_notes", "blockers": [string], "nits": [string], "notes": string } Diff: {diff content} ``` ## Workflow When writing a subagent brief: 1. **Write the goal sentence first.** If it has "and," split into two subagents. 2. **List what context the subagent needs.** Drop anything not strictly necessary. 3. **Write the constraints.** Autonomy, budget, don'ts. 4. **Write the return shape last but explicit.** 5. **Re-read the brief from a cold-start perspective.** Could a competent stranger do this task from this brief alone? If not, fix. 6. **Check token count.** Under ~1500 tokens. ## Verification Manual checklist for each brief: - [ ] Goal in one sentence (no "and"). - [ ] Why included (one line max). - [ ] Relevant context only, no general background. - [ ] Explicit autonomy boundary. - [ ] Time/effort budget stated. - [ ] Concrete return shape (JSON or markdown sections). - [ ] Length cap on return. - [ ] No motivational filler. ## When to skip this skill - "Subagent" is your own next message in the same context. No briefing needed. - Tightly-scoped tool call, not an agent (no LLM-driven reasoning loop). - Briefs from a fixed template you cannot edit. ## Related skills - [`forge-multi-agent`](../forge-multi-agent/SKILL.md) - when to spawn, parallelism, orchestration patterns. - [`forge-subagent-eval`](../forge-subagent-eval/SKILL.md) - what to do with the brief's output. - [`forge-prompt-engineering`](../../llm/forge-prompt-engineering/SKILL.md) - prompt structure in general.