Agent OS — Prompts
Agent OS's prompt design lives entirely in the five command markdown files installed to .claude/commands/agent-os/. There are no CLAUDE.md templates, no system prompts inside install scripts, and no skill files. The commands are the prompts.
Prompting Technique: AskUserQuestion-first
Every command opens with the same structural rule: always use the AskUserQuestion tool when asking the user anything. This is not a suggestion — it appears as a bolded guideline in every single command file. The technique ensures the AI never proceeds speculatively; it always explicitly surfaces a structured question and waits for a response before the next step.
Verbatim Excerpt 1 — discover-standards.md (full file, condensed to first major section)
Source: commands/agent-os/discover-standards.md
# Discover Standards
Extract tribal knowledge from your codebase into concise, documented standards.
## Important Guidelines
- **Always use AskUserQuestion tool** when asking the user anything
- **Write concise standards** — Use minimal words. Standards must be scannable by AI agents without bloating context windows.
- **Offer suggestions** — Present options the user can confirm, choose between, or correct. Don't make them think harder than necessary.
## Process
### Step 1: Determine Focus Area
Check if the user specified an area when running this command. If they did, skip to Step 2.
If no area was specified:
1. Analyze the codebase structure (folders, file types, patterns)
2. Identify 3-5 major areas. Examples:
- **Frontend areas:** UI components, styling/CSS, state management, forms, routing
- **Backend areas:** API routes, database/models, authentication, background jobs
- **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure
3. Use AskUserQuestion to present the areas:
I've identified these areas in your codebase:
- API Routes (src/api/) — Request handling, response formats
- Database (src/models/, src/db/) — Models, queries, migrations
- React Components (src/components/) — UI patterns, props, state
- Authentication (src/auth/) — Login, sessions, permissions
Which area should we focus on for discovering standards? (Pick one, or suggest a different area)
Wait for user response before proceeding.
### Step 3: Ask Why, Then Draft Each Standard
**IMPORTANT:** For each selected standard, you MUST complete this full loop before moving to the next standard:
1. **Ask 1-2 clarifying questions** about the "why" behind the pattern. Use your AskUserQuestion tool for this.
2. **Wait for user response**
3. **Draft the standard** incorporating their answer
4. **Confirm with user** before creating the file
5. **Create the file** if approved
Example questions to ask (adapt based on the specific standard):
- "What problem does this pattern solve? Why not use the default/common approach?"
- "Are there exceptions where this pattern shouldn't be used?"
- "What's the most common mistake a developer or agent makes with this?"
**Do NOT batch all questions upfront.** Process one standard at a time through the full loop.
Technique highlighted: The "ask-why" loop is the core extraction engine. For every discovered pattern, the agent is instructed to probe the reason behind the pattern before writing it down. This produces richer standards that capture intent, not just syntax. The explicit instruction "Do NOT batch all questions upfront" forces a tight human-in-the-loop cycle rather than an autonomous bulk run.
Source: commands/agent-os/inject-standards.md
# Inject Standards
Inject relevant standards into the current context, formatted appropriately for the situation.
## Usage Modes
This command supports two modes:
### Auto-Suggest Mode (no arguments)
/inject-standards
Analyzes context and suggests relevant standards.
### Explicit Mode (with arguments)
/inject-standards api # All standards in api/
/inject-standards api/response-format # Single file
/inject-standards api/response-format api/auth # Multiple files
/inject-standards root # All standards in the root folder
/inject-standards root/naming # Single file from root folder
Directly injects specified standards without suggestions.
### Step 1: Detect Context Scenario
**Three scenarios:**
1. **Conversation** — Regular chat, implementing code, answering questions
2. **Creating a Skill** — Building a `.claude/skills/` file
3. **Shaping/Planning** — In plan mode, building a spec, running `/shape-spec`
**Detection logic:**
- If currently in plan mode OR conversation clearly mentions "spec", "plan", "shape" → **Shaping/Planning**
- If conversation clearly mentions creating a skill, editing `.claude/skills/`, or building a reusable procedure → **Creating a Skill**
- Otherwise → **Ask to confirm** (do not assume)
**If neither skill nor plan is clearly detected**, use AskUserQuestion to confirm:
I'll inject the relevant standards. How should I format them?
- Conversation — Read standards into our chat (for implementation work)
- Skill — Output file references to include in a skill you're building
- Plan — Output file references to include in a plan/spec
Which scenario? (1, 2, or 3)
Always ask when uncertain — don't assume conversation by default.
#### Scenario: Creating a Skill
First, use AskUserQuestion to determine how to include the standards:
How should these standards be included in your skill?
- References — Add @ file paths that point to the standards (keeps skill lightweight, standards stay in sync)
- Copy content — Paste the full standards content into the skill (self-contained, but won't update if standards change)
Which approach? (1 or 2)
**If References (option 1):**
Be sure to include references to the following standards files in the appropriate location in the file(s) that make up this skill:
@agent-os/standards/api/response-format.md
@agent-os/standards/api/error-handling.md
@agent-os/standards/global/naming.md
Technique highlighted: Context-adaptive output. The same command produces three completely different outputs depending on whether the user is in a chat, building a skill, or shaping a spec. This prevents the common failure mode of injecting verbose content into a plan that should just reference files. The @file-path reference format for skill/plan scenarios is deliberately lightweight — it keeps token cost near zero while maintaining live linkage to standards.
Verbatim Excerpt 3 — shape-spec.md (plan mode gate + Task 1 convention)
Source: commands/agent-os/shape-spec.md
# Shape Spec
Gather context and structure planning for significant work. **Run this command while in plan mode.**
## Prerequisites
This command **must be run in plan mode**.
**Before proceeding, check if you are currently in plan mode.**
If NOT in plan mode, **stop immediately** and tell the user:
Shape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.
Do not proceed with any steps below until confirmed to be in plan mode.
### Step 6: Generate Spec Folder Name
Create a folder name using this format:
YYYY-MM-DD-HHMM-{feature-slug}/
Where:
- Date/time is current timestamp
- Feature slug is derived from the feature description (lowercase, hyphens, max 40 chars)
Example: `2026-01-15-1430-user-comment-system/`
### Step 7: Structure the Plan
Now build the plan with **Task 1 always being "Save spec documentation"**.
Present this structure to the user:
Here's the plan structure. Task 1 saves all our shaping work before implementation begins.
Task 1: Save Spec Documentation
Create agent-os/specs/{folder-name}/ with:
- plan.md — This full plan
- shape.md — Shaping notes (scope, decisions, context from our conversation)
- standards.md — Relevant standards that apply to this work
- references.md — Pointers to reference implementations studied
- visuals/ — Any mockups or screenshots provided
Technique highlighted: Hard prerequisite guard ("stop immediately and tell the user"). The plan mode gate is not advisory — if the command detects it's not in plan mode, execution halts. This ensures spec shaping always happens inside Claude Code's plan mode context, which provides the correct execution semantics (no accidental code writes during planning). The "Task 1 always saves spec docs" convention creates a durable, inspectable artifact of every shaping session before a single line of code is written.
Source: profiles/default/global/tech-stack.md
# Tech Stack
## Frontend
- React 18 with TypeScript
- Tailwind CSS v4 for styling
- Vite for build tooling
## Backend
- Node.js with Express
- TypeScript
## Database
- PostgreSQL
## Other
Technique highlighted: The standard file format is intentionally minimal — no prose, no rationale, no caveats. The design philosophy explicitly states "every word costs tokens" and standards should be "scannable by AI agents without bloating context windows." The default tech-stack standard is a 14-line template, not a 200-line architecture document.
Prompting Anti-Pattern: Explicit "Bad" Example in discover-standards.md
The command file includes a side-by-side "Good vs. Bad" example that doubles as prompt engineering guidance for standards authors:
## Writing Concise Standards
**Good:**
```markdown
# Error Responses
Use error codes: `AUTH_001`, `DB_001`, `VAL_001`
\`\`\`json
{ "success": false, "error": { "code": "AUTH_001", "message": "..." } }
\`\`\`
- Always include both code and message
- Log full error server-side, return safe message to client
Bad:
# Error Handling Guidelines
When an error occurs in our application, we have established a consistent pattern for how errors should be formatted and returned to the client. This helps maintain consistency across our API and makes it easier for frontend developers to handle errors appropriately...
[continues for 3 more paragraphs]
This embedded anti-pattern guidance enforces the token-economy philosophy at the content level, not just the architecture level.
---
## Summary of Prompting Techniques
| Technique | Where Used | Effect |
|---|---|---|
| `AskUserQuestion` mandate | All 5 commands | Forces human-in-the-loop; no autonomous bulk actions |
| Ask-why before drafting | `discover-standards` | Captures intent and rationale, not just syntax |
| Context scenario detection | `inject-standards` | Adaptive output format (inline vs. reference vs. copy) |
| Hard prerequisite guard | `shape-spec` | Prevents plan-mode features from running outside plan mode |
| Task 1 = save spec docs | `shape-spec` | Guarantees spec durability before implementation begins |
| Token-economy writing rules | `discover-standards` | Teaches users to write AI-friendly standards |
| Timestamped folder naming | `shape-spec` | Makes specs chronologically discoverable across sessions |