# Prompt Architect Version: 1.0.0 Status: ACTIVE ## Purpose Design reusable production prompts and agent instructions from a task's goals, inputs, constraints, workflow, failure modes, and expected outputs. This skill is for prompts that will be used repeatedly. The goal is not: ```text WRITE A VERY LONG PROMPT ``` The goal is: ```text BUILD THE SMALLEST RELIABLE INSTRUCTION SYSTEM ``` --- # 1. Trigger Conditions Use this skill when: * a task will be repeated * a workflow needs standardization * several people or agents should perform a task consistently * the current prompt produces inconsistent results * a successful manual workflow should become reusable * building a specialized AI agent * creating project prompts * creating a reusable role * converting a procedure into agent instructions Do not create a permanent prompt for every one-time request. --- # 2. Core Architecture A robust reusable prompt usually needs some combination of: ```text ROLE OBJECTIVE INPUT CONTRACT CONTEXT PROCEDURE CONSTRAINTS TOOL RULES OUTPUT CONTRACT FAILURE HANDLING VERIFICATION ``` Not every prompt requires every section. Include only what materially improves behavior. --- # 3. Start with the Task Define the task in one sentence. Example: ```text Review an ASP Classic endpoint for security, correctness, maintainability, and consistency with the existing project. ``` If the task cannot be described clearly in one or two sentences, the prompt may be trying to do too many jobs. --- # 4. Define the User Identify who consumes the result. Examples: ```text developer system administrator manager student end user technical reviewer ``` Output quality often depends on the consumer. --- # 5. Define Inputs Identify what the prompt will receive. Example: ```text Required: - source file - project instructions - related configuration Optional: - error logs - test results ``` A reusable prompt should not depend on hidden context whenever avoidable. --- # 6. Define Output Determine exactly what the prompt should produce. Weak: ```text Review the code. ``` Better: ```text Return: 1. blocking findings 2. important findings 3. optional improvements 4. verification recommendations For each finding include: - location - issue - why it matters - smallest recommended fix ``` Output contracts reduce ambiguity. --- # 7. Separate Stable and Variable Information Stable information belongs in the reusable prompt. Variable information should become placeholders. Example: Stable: ```text Review authentication, input validation, error handling, data access, and consistency with repository conventions. ``` Variable: ```text {{TARGET_FILE}} {{PROJECT_CONTEXT}} {{USER_GOAL}} ``` Do not hard-code temporary details into reusable prompts. --- # 8. Role Use a role when expertise or perspective materially changes the work. Good: ```text Act as a senior application security reviewer for a legacy ASP Classic application. ``` Weak: ```text You are the world's greatest genius programmer. ``` Roles should affect behavior, not inflate tone. --- # 9. Objective State the actual outcome. Example: ```text Identify realistic security defects and provide the smallest maintainable corrections without redesigning unrelated parts of the application. ``` This combines: ```text GOAL + SCOPE + QUALITY BAR ``` --- # 10. Context Contract Tell the agent which evidence matters. Example: ```text Before reviewing the target file: 1. read AGENTS.md 2. inspect relevant authentication code 3. inspect at least one analogous endpoint 4. inspect the application's error-handling convention ``` This is stronger than giving generic advice. --- # 11. Procedure Define observable steps. Example: ```text 1. inspect the target 2. identify trust boundaries 3. trace user-controlled inputs 4. trace data access 5. inspect output encoding 6. identify findings 7. verify findings against project conventions 8. rank by severity ``` Do not require hidden chain-of-thought. Ask for operations that can be performed and verified. --- # 12. Do Not Request Private Chain-of-Thought Avoid instructions such as: ```text Show every reasoning step. Reveal your complete chain of thought. Think step by step and print everything. ``` Instead use: ```text Inspect the evidence. Identify assumptions. Compare alternatives. State the chosen approach and concise rationale. Report verification evidence. ``` The workflow matters more than exposing internal reasoning. --- # 13. Constraints Define explicit boundaries. Examples: ```text Do not introduce a new framework. Do not change public URL behavior. Do not replace parameterized SQL with string concatenation. Do not modify unrelated files. Do not invent APIs not present in the repository. ``` Negative constraints are useful when they protect important boundaries. --- # 14. Avoid Giant Ban Lists Do not add dozens of arbitrary negative rules unless evidence shows they are needed. Too many constraints can create: ```text conflicts instruction dilution unexpected refusal poor prioritization ``` Prefer high-value constraints. --- # 15. Tool Rules If tools are available, specify when they matter. Example: ```text Search the repository before claiming a class does not exist. Run the build after code changes. Inspect the diff before completion. ``` Do not describe every possible tool call. Define behavioral rules. --- # 16. Verification A reusable prompt should define success. Examples: ```text Run existing tests. Validate generated JSON. Compare imported and expected row counts. Check all referenced files exist. Verify commands against the target environment. ``` Prompt outputs are stronger when verification is part of the task. --- # 17. Failure Handling Define what should happen when the task cannot proceed normally. Example: ```text If a critical project fact cannot be discovered, ask only the minimum targeted question needed. If testing cannot be performed, state exactly what remains unverified. ``` This prevents silent guessing. --- # 18. Interaction Mode Specify whether the task should be: ```text AUTONOMOUS INTERACTIVE SOCRATIC REVIEW-ONLY ``` Example: ```text For learning: one concept → one drill → wait. For code generation: produce the complete implementation unless blocked. ``` Choosing the wrong interaction mode is a common prompt failure. --- # 19. Persona Design For reviewer or adversarial prompts, define incentives rather than simply saying: ```text Be critical. ``` Better: ```text You are the operations engineer responsible for recovering this deployment at 2 AM. Your primary concern is recoverability. Treat any irreversible step without rollback as high risk. ``` This creates realistic scrutiny. --- # 20. Prompt Skeleton A general reusable structure: ```text # Role [Relevant expertise/perspective] # Objective [Exact task outcome] # Inputs [Required and optional inputs] # Context [What must be inspected or understood] # Procedure 1. [...] 2. [...] 3. [...] # Constraints - [...] - [...] # Verification [How correctness is checked] # Failure Handling [What to do if blocked or uncertain] # Output [Exact expected structure] ``` --- # 21. Test the Prompt Do not save an important reusable prompt without testing it. Test at least: ```text NORMAL CASE INCOMPLETE CASE EDGE CASE ``` For high-impact prompts also test: ```text ADVERSARIAL OR AMBIGUOUS CASE ``` --- # 22. Normal Case Test Use realistic valid input. Ask: ```text Did the prompt produce the intended structure? Did it follow project constraints? Was the output useful without manual repair? ``` --- # 23. Incomplete Input Test Remove important but discoverable context. Check whether the prompt: ```text discovers it asks a precise question or safely identifies what is missing ``` It should not hallucinate. --- # 24. Edge Case Test Use unusual but valid input. Examples: ```text empty dataset very large file legacy version missing optional field unusual directory structure ``` The goal is to expose brittle assumptions. --- # 25. Ambiguity Test Give input that could be interpreted multiple ways. Check whether the prompt: ```text discovers context asks a targeted question or states a safe assumption ``` rather than arbitrarily choosing. --- # 26. Constraint Test Try to trigger behavior the prompt forbids. Example: If the prompt says: ```text Do not introduce dependencies. ``` give it a task where adding a package is tempting. Verify that it respects the boundary. --- # 27. Output Test Ensure the output contract is useful. Ask: ```text Can another person or agent act directly on this output? ``` If extensive manual restructuring is always needed, improve the contract. --- # 28. Prompt Refinement After failure: ```text PRESERVE FAILED INPUT PRESERVE FAILED OUTPUT DIAGNOSE FAILURE MAKE SMALLEST CHANGE RERUN SAME TEST ``` Use: ```text .ai/skills/prompt-debugger/SKILL.md ``` Do not rewrite everything immediately. --- # 29. Prompt Versioning Useful production prompts should be versioned. Example: ```text security-review_v1.0.md security-review_v1.1.md ``` Or track version inside the file. Version changes should reflect meaningful behavior changes. --- # 30. Prompt Changelog For important prompts, note: ```text what changed why what failed how the change was tested ``` Prompt evolution should be evidence-driven. --- # 31. Extract Prompt from Successful Work A powerful creation method is: ```text SUCCESSFUL TASK ↓ WHAT PROCEDURE PRODUCED IT? ↓ WHAT INPUTS MATTERED? ↓ WHAT BOUNDARIES MATTERED? ↓ GENERALIZE ↓ PROMPT ``` Use the reverse-engineer or skill-extractor skill when useful. --- # 32. Prompt vs Skill Decision Create a prompt when: ```text the primary need is a repeatable task launch or output format ``` Create a skill when: ```text the primary need is a reusable operational procedure ``` Example: Prompt: ```text Review this pull request. ``` Skill: ```text How to conduct a security-focused code review. ``` A prompt may invoke a skill. --- # 33. Prompt vs AGENTS.md Do not put every reusable prompt rule into `AGENTS.md`. Root instructions should define broad behavior. Task-specific behavior belongs in prompts or skills. --- # 34. Prompt Composition Complex tasks may compose: ```text ROOT INSTRUCTIONS + PROJECT CONTEXT + SKILL + TASK PROMPT + CURRENT INPUT ``` This is usually better than one giant permanent prompt. --- # 35. Information Density Prefer precise instructions with high information value. Weak: ```text Be thoughtful, careful, thorough, professional, excellent, detailed, accurate, helpful, expert, comprehensive. ``` Better: ```text Identify blocking defects first. For each defect cite the affected component, explain the failure mode, and give the smallest safe correction. ``` Specific behavior beats adjectives. --- # 36. Tone Constraints Tone rules should be operational. Example: ```text Use direct language. Avoid unnecessary preamble. Do not use generic praise. Prefer concrete examples. ``` Avoid attempting to control every word. --- # 37. Prompt Anti-Fluff When writing user-facing output, useful defaults include: ```text start with the answer use active voice prefer concrete nouns and verbs remove redundant summary avoid generic corporate filler ``` For a final editing pass use: ```text .ai/skills/coffee-chat-editor/SKILL.md ``` --- # 38. Examples in Prompts Examples can strongly constrain behavior. Use examples when: ```text format is unusual distinctions are subtle output keeps drifting failure cases are important ``` Avoid dozens of examples. One or two strong examples are often enough. --- # 39. Few-Shot Pattern When examples are useful: ```text INPUT EXAMPLE EXPECTED OUTPUT SECOND DIFFERENT INPUT EXPECTED OUTPUT ``` Ensure examples demonstrate the rule rather than accidentally hard-coding one domain case. --- # 40. Self-Improvement Improve a reusable prompt when real use reveals: * recurring failure * repeated manual cleanup * missing constraints * poor interaction mode * weak verification * excessive output * insufficient project discovery * incorrect tool assumptions Capture evidence before permanent change. --- # 41. Prompt Deprecation Retire a prompt when: ```text its workflow is obsolete a skill replaces it a better prompt fully supersedes it technology changes it repeatedly causes worse outcomes ``` Do not maintain unused prompts indefinitely. --- # 42. Output Contract for This Skill When using Prompt Architect, produce: ```text PROMPT PURPOSE INPUT CONTRACT REUSABLE PROMPT TEST CASES EXPECTED BEHAVIOR KNOWN LIMITATIONS VERSION ``` For simple prompts, compress this. --- # 43. Changelog ## 1.0.0 Initial active version. Introduced: * role/objective/context design * stable-vs-variable separation * observable procedures instead of exposed chain-of-thought * negative constraints * output contracts * failure handling * interaction modes * persona incentives * prompt testing * versioning * modular prompt composition