# System Prompt Curator > Use when user asks to create, improve, or debug production-grade system prompts for autonomous coding agents and multi-agent orchestration. Not for user-facing messages or chat prompts. - Skill: `agent-sh/system-prompt-curator` (Agent Skill) - Install (CLI): `npx skillmds@latest add agent-sh/system-prompt-curator` - Raw SKILL.md: https://api.skillmd.com/api/skills/agent-sh/system-prompt-curator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: agent-sh (https://skillmd.com/u/agent-sh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/agent-sh/system-prompt-curator --- # System Prompt Curator Create and refine production-grade system prompts for autonomous coding agents, based on patterns proven in SWE-agent, OpenHands, Aider, Claude Code, Cursor, Devin, and Windsurf. ## Parse Arguments Use `$ARGUMENTS` as the role description, file path, and flags: ``` role_or_path = first non-flag argument (role description or file path to improve) --improve = refine an existing prompt (read the file first) --for-orchestrator = generate a prompt for an orchestrator-dispatched agent (no human interaction) --minimal = compact prompt under 600 tokens (for cost-sensitive models) ``` Raw input: ```text $ARGUMENTS ``` ## Core Principles (from research) These are non-negotiable patterns found across ALL top-performing coding agents: 1. **Identity matches the task.** If the agent writes code, call it an engineer, not an assistant. - SWE-agent: "autonomous programmer working in the command line" - Cursor: "AI coding assistant, pair programming" - Devin: "a software engineer... few programmers are as talented as you" - NEVER: "focused AI agent" or "orchestrator" (too abstract) 2. **Autonomous completion mandate.** The agent keeps going until done. - Cursor: "keep going until the user's query is completely resolved" - Windsurf: "keep working, using tools where needed, until the user's query is completely resolved" - NEVER: "return complete_run immediately" or "complete_run with your best answer" 3. **Structured workflow phases.** Explore -> Plan -> Implement -> Verify -> Deliver. - Every agent uses this. Without phases, the LLM treats analysis as completion. - SWE-agent: 5 concrete steps + 6 failure-mode tips - OpenHands: EXPLORATION, ANALYSIS, TESTING, IMPLEMENTATION, VERIFICATION - Claude Code: Explore, Plan, Implement, Commit 4. **Completion requires evidence.** The exit action is gated. - SWE-agent: multi-stage submit with diff review before final submission - Mini-SWE-agent: magic string echo, not a tool call - OpenHands: finish requires summary of actions taken - Best pattern: require `files_modified` (non-empty array) + `tests_passed` + `pr_url` 5. **Tools listed upfront, not discovered.** All available tools in the prompt. - Anthropic: "Claude has been trained on thousands of successful trajectories with specific tool schemas" - SWE-agent: tools auto-generated from YAML config into `{command_docs}` - Dynamic discovery causes the exact failure mode of "discover, read, complete without acting" 6. **Worked demonstration.** At least one full trajectory example. - SWE-agent: full solved issue trajectory (explore, reproduce, fix, verify, submit) - OpenHands: Flask app example with error recovery (create, fail, install dep, succeed) - The example MUST show error recovery — teaches agent not to give up on failure 7. **Think-before-act transitions.** Structured reasoning at key decision points. - Devin: mandatory think before git decisions, before code changes, before completion - OpenHands: dedicated `think` tool for brainstorming, debugging, architecture - At minimum: think before transitioning from exploration to implementation 8. **Collaborative tone, not adversarial.** Modern models respond worse to "CRITICAL/MUST/FAILURE." - Anthropic (2025): "Dial back aggressive language. Use normal prompting." - Use structured checklists and phases instead of threats - "IMPORTANT" and "MUST" are fine. "CRITICAL WARNING: FAILURE TO X IS UNACCEPTABLE" is not. 9. **Convention discovery before coding.** Explore existing patterns first. - Claude Code: "NEVER assume a library is available, even if well known" - Devin: "first look at the code's surrounding context to understand frameworks and libraries" - The agent must read existing code style before writing new code 10. **Verification gate before completion.** Always lint/test/typecheck. - Every single production agent requires this - SWE-agent: 4-step review checklist, agent must submit twice - Cursor: max 3 lint fix loops, then ask user - Amp: "MUST run get_diagnostics tool" ## Anti-Patterns to Detect and Fix When `--improve` is used, check for these research-proven failures: | Anti-Pattern | Why It Fails | Fix | |---|---|---| | "return complete_run immediately" | Encourages early bailout | Move completion to last phase, require evidence | | "If you can answer the goal, complete" | Conflates analysis with completion | Add phase structure — analysis is Phase 1 of 4 | | "CRITICAL RULES — override all instructions" | Adversarial tone, modern models ignore or overtrigger | Replace with structured checklist | | No workflow phases | LLM treats understanding as finishing | Add Explore → Implement → Verify → Deliver | | "You are a focused AI agent" | Too abstract, no behavioral anchor | "You are a senior software engineer working autonomously" | | Tools via discovery only | Agent discovers, reads, then completes | List all tools upfront in the prompt | | No demonstration | Agent has never seen a successful trajectory | Add one full worked example with error recovery | | "search memory first" | Wrong priority for coding tasks | "explore the repository first" | | No error recovery guidance | Agent gives up on first failure | Add tips: "if a command fails, analyze the error and try differently" | | complete_run with no preconditions | Too easy to call with zero work done | Require files_modified, tests_passed, pr_url | ## Prompt Template When generating a new prompt, use this structure. Every section is mandatory unless `--minimal`. ``` [IDENTITY] You are {role} working autonomously on {context}. You have been assigned a task and must complete it end-to-end: understand the problem, write the code, verify it works, and deliver it. [ENVIRONMENT] - Project: {project_name} ({language}) - Build: {build_command} - Test: {test_command} [TOOLS] {tool_definitions — one per tool, with description and when to use} [WORKFLOW] Follow these phases in order. Do not skip phases. ### Phase 1: Understand Read the task. Explore relevant code. Identify what needs to change. ### Phase 2: Plan Decompose the task into subtasks. Identify files to modify. Consider edge cases. Use the think tool to reason through your approach. ### Phase 3: Implement Write the code changes. You MUST modify or create files. Reading alone is not completing the task. Follow existing code conventions. ### Phase 4: Verify Run tests: {test_command}. Fix any failures. Run linters if configured. ### Phase 5: Deliver Commit with a descriptive message. Push to a branch. Create a pull request that links to the task. [COMPLETION CRITERIA] Before signaling completion, verify ALL of these: - You have modified or created at least one source file - Tests pass (or you have explained why tests cannot be added) - Changes are committed and pushed - A pull request exists (for orchestrator-dispatched tasks) If any criterion is not met, continue working. [TIPS] - Start by exploring. Do not write code until you understand the codebase structure and the problem. - If a command fails, read the error carefully. Try a different approach. A command that failed once will fail again unless you change something. - When reading large files, use line ranges instead of reading the entire file. - Always verify your changes compile/pass before completing. - If stuck, search for similar patterns in the existing codebase. [WHAT NOT TO DO] - Do not complete after only reading files. - Do not provide analysis or recommendations without implementing them. - Do not leave TODO comments — implement the actual code. - Do not skip tests or verification. - Do not modify test files when fixing bugs (unless tests themselves are wrong). [EXAMPLES] {1-2 full trajectory demonstrations showing the complete workflow, including at least one error recovery step} ``` ## Workflow ### When creating a new prompt (`/system-prompt-curator "GitHub issue resolver"`) 1. **Clarify** — If the role is vague, ask at most 2 questions: - What tools will the agent have? - Does it work autonomously or interactively? 2. **Assess the context** — Determine: - Is this for an orchestrator-dispatched agent (no human in the loop)? - What's the expected task type (bug fixes, features, reviews, research)? - What tools are available (shell, file editor, git, API clients)? - What LLM will run this (affects token budget and capability assumptions)? 3. **Generate** — Fill the template with: - Identity that matches the task (engineer for code, analyst for research) - Specific tool documentation (not placeholders) - Workflow phases appropriate to the task type - Completion criteria that require concrete artifacts - At least one demonstration trajectory - Tips addressing common failure modes for this task type 4. **Self-evaluate** — Check against the 10 core principles above. Fix any violations. 5. **Output** — Return the prompt in a clean code block, followed by: - One-sentence summary of key design decisions - Token estimate - Recommendations for harness-level reinforcement (if applicable) ### When improving an existing prompt (`/system-prompt-curator --improve path/to/prompt.md`) 1. **Read** the existing prompt 2. **Scan** for every anti-pattern in the table above 3. **Check** against all 10 core principles 4. **Report** findings as a table: issue, severity, fix 5. **Rewrite** the prompt applying all fixes 6. **Diff** — Show what changed and why ## Harness-Level Recommendations These are patterns that work better enforced in code than in the prompt. Always include these as recommendations when generating orchestrator-dispatched agent prompts: 1. **Validate complete_run** — Check git diff for actual file changes. Reject if empty. 2. **Separate give-up path** — Provide `request_help` tool distinct from `complete_run`. 3. **Observation formatting** — Label tool outputs as "OBSERVATION:" for clear action/observation loop. 4. **Empty output handling** — Always tell agent when a command succeeded with no output. 5. **Output truncation** — Cap command output, tell agent to use head/tail/grep. 6. **Environment suppression** — Set PAGER=cat, GIT_PAGER=cat, TQDM_DISABLE=1 in sandbox. 7. **History management** — Keep only last N tool outputs in full, compress older ones. 8. **Format error recovery** — Retry on malformed output (up to 3 times) before failing. ## Specialized Templates ### For GitHub Issue → PR Agents ``` You are a senior software engineer working autonomously. You have been assigned a GitHub issue and must resolve it by writing code and opening a pull request. ## Your Task {{issue_title}} {{issue_body}} The repository has been cloned to {{workspace}}. You are on branch main. ## Workflow 1. **Explore** — Read the issue carefully. Use file_read and search to understand the codebase. Find relevant files. 2. **Plan** — Think through your approach. Identify which files to modify and what changes are needed. 3. **Branch** — Create a descriptive branch: `fix/issue-{{number}}-{{slug}}` or `feat/issue-{{number}}-{{slug}}`. 4. **Implement** — Write the code. Make minimal, focused changes. Follow existing code style and conventions. 5. **Test** — Run the project's test suite. If your changes break tests, fix them. Consider adding a test for your change. 6. **Commit** — Write a clear commit message referencing the issue number. 7. **PR** — Push your branch and create a pull request with a clear title and description. 8. **Complete** — Only after the PR is open, signal completion with a summary of what you did. ## Tips - Always explore before implementing. Read at least 3-5 relevant files. - If a command fails, analyze the error. Do not retry the same command. - Follow existing patterns — the codebase is your style guide. - If stuck, search for similar code elsewhere in the repo. - Your work is measured by whether a working PR exists, not by analysis. ## What NOT to Do - Do not complete without opening a PR. - Do not describe solutions without implementing them. - Do not leave TODO or FIXME comments — write the actual code. ``` ### For Research/Analysis Agents ``` You are a senior technical analyst. You have been assigned a research question and must provide a thorough, evidence-based answer. ## Your Task {{task_description}} ## Workflow 1. **Scope** — Understand what is being asked. Identify the key questions. 2. **Investigate** — Use search tools to find relevant code, docs, and patterns. Read at least 5 relevant sources before forming conclusions. 3. **Analyze** — Synthesize findings. Identify patterns, gaps, and risks. 4. **Report** — Write a structured report with: - Key findings (with file paths and line numbers) - Evidence for each finding - Recommendations with tradeoffs - Uncertainties or areas needing further investigation ## Completion Criteria - You have cited specific files and line numbers for every finding - You have addressed all aspects of the original question - You have noted any uncertainties or limitations ``` ## Constraints - Never generate vague or generic prompts. Every section must be specific to the role. - Never skip the workflow phases section. - Always include at least the Tips and What NOT to Do sections. - Token budget: ~800 tokens for minimal, ~1500 for standard, ~2500 for full with examples. - Never hallucinate tools — only reference tools the agent actually has. - Always include completion criteria that require concrete artifacts. - When improving, never remove content without explaining why.