13KB
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:
WRITE A VERY LONG PROMPT
The goal is:
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:
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:
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:
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:
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:
Review the code.
Better:
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:
Review authentication, input validation, error handling,
data access, and consistency with repository conventions.
Variable:
{{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:
Act as a senior application security reviewer
for a legacy ASP Classic application.
Weak:
You are the world's greatest genius programmer.
Roles should affect behavior, not inflate tone.
9. Objective
State the actual outcome.
Example:
Identify realistic security defects and provide the
smallest maintainable corrections without redesigning
unrelated parts of the application.
This combines:
GOAL
+
SCOPE
+
QUALITY BAR
10. Context Contract
Tell the agent which evidence matters.
Example:
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:
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:
Show every reasoning step.
Reveal your complete chain of thought.
Think step by step and print everything.
Instead use:
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:
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:
conflicts
instruction dilution
unexpected refusal
poor prioritization
Prefer high-value constraints.
15. Tool Rules
If tools are available, specify when they matter.
Example:
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:
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:
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:
AUTONOMOUS
INTERACTIVE
SOCRATIC
REVIEW-ONLY
Example:
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:
Be critical.
Better:
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:
# 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:
NORMAL CASE
INCOMPLETE CASE
EDGE CASE
For high-impact prompts also test:
ADVERSARIAL OR AMBIGUOUS CASE
22. Normal Case Test
Use realistic valid input.
Ask:
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:
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:
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:
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:
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:
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:
PRESERVE FAILED INPUT
PRESERVE FAILED OUTPUT
DIAGNOSE FAILURE
MAKE SMALLEST CHANGE
RERUN SAME TEST
Use:
.ai/skills/prompt-debugger/SKILL.md
Do not rewrite everything immediately.
29. Prompt Versioning
Useful production prompts should be versioned.
Example:
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:
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:
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:
the primary need is a repeatable task launch or output format
Create a skill when:
the primary need is a reusable operational procedure
Example:
Prompt:
Review this pull request.
Skill:
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:
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:
Be thoughtful, careful, thorough, professional, excellent,
detailed, accurate, helpful, expert, comprehensive.
Better:
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:
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:
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:
.ai/skills/coffee-chat-editor/SKILL.md
38. Examples in Prompts
Examples can strongly constrain behavior.
Use examples when:
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:
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:
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:
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