---
name: writing-agent-directives
description: Use when writing instructions that guide agent behavior - skills, AGENTS.md files, agent prompts, system prompts.
---

# Writing Agent Directives

Apply `prompt-security-hardening` alongside this skill. Directives that demonstrate unsafe secrets handling teach agents to leak secrets.

## Core Principles

**1. Agents are smart.** Only write what it doesn't already know. Challenge each line: does this justify its token cost?

**2. Positive > Negative framing.** "Don't do X" triggers thinking about X (pink elephant problem). Say what TO do, not what to avoid.

```markdown
# Bad: triggers the behavior
Don't create duplicate files

# Good: directs to correct behavior
Update existing files in place
```

**3. Context motivates compliance.** Explain WHY, not just WHAT. Agents generalize from motivation.

```markdown
# Less effective
NEVER use ellipses

# More effective
Your response will be read aloud by a text-to-speech engine, so never use ellipses since the TTS engine cannot pronounce them.
```

**4. Placement matters.** Instructions at prompt start and end receive higher attention. Critical rules go at boundaries.

**5. ~150 instruction limit.** More instructions degrade compliance across every rule, not just the new ones. Prune ruthlessly.

**6. Repetition enforces critical rules.** For high-stakes requirements, repeat with different framings.

## Token Efficiency

**Targets:**
- Frequently-loaded directives: <200 words
- Skills/`AGENTS.md`: <500 lines total
- Reference --help instead of documenting flags
- Cross-reference other skills instead of repeating

**Progressive disclosure:** Main file is overview + links. Reference files load on-demand.

## Discovery (for Skills)

The `description` field determines if the agent finds your skill.

**Format:** Start with "Use when..." + specific triggers + what it does.

**Write in third person.** Injected into system prompt.

```yaml
# Bad: vague, first person
description: I help with async testing

# Good: triggers + action, third person
description: Use when tests have race conditions or timing dependencies - replaces arbitrary timeouts with condition polling
```

**Keywords:** Include error messages, symptoms, tool names the agent might search for.

## Compliance Techniques

Agents are highly responsive to instructions. Lead with context and motivation; reserve imperatives for critical boundaries.

### Primary: Context + Motivation

Explain WHY the rule exists. Agents generalize from the explanation:

```markdown
# Instead of raw authority
You MUST run tests before committing.

# Provide motivation
Run tests before committing. Untested commits break CI for the whole team and block other developers from merging their work.
```

### Secondary: Structural Enforcement

Use structure to make compliance the path of least resistance:

| Pattern | Example |
|---------|---------|
| Workflow steps | Numbered steps with verification gates |
| Task tracking | Checklists without persistent tracking are easily skipped |
| Forced commitment | "Announce: I'm using [skill]" |
| Explicit blocking | "If X happens, stop and do Y instead" |

### Escalation: Imperatives (Use Sparingly)

Aggressive language ("YOU MUST", "CRITICAL") can cause overtriggering. Use normal language first:

```markdown
# Often sufficient for 5.x
Use this tool when searching for files.

# Reserve imperatives for true boundaries
Never commit secrets to version control.
```

Close loopholes when needed, but prefer context over authority:

```markdown
# Good: context + loophole closure
Write the test first. Code written before its test tends to test the implementation rather than the behavior, making refactoring harder later. If you find yourself with untested code, delete it and start with the test.
```

### By Skill Type

| Type | Approach |
|------|----------|
| Discipline (TDD, verification) | Context + structural enforcement + loophole closure |
| Technique (patterns, how-to) | Clear steps, "we want quality" framing |
| Reference (documentation) | Clarity only, no persuasion needed |

## Structure Patterns

### XML for Directives and Format Control

Agents parse XML effectively. Use for multi-part directives:

```xml
<task>What to accomplish</task>
<constraints>Hard requirements</constraints>
<output_format>Expected structure</output_format>
<examples>Input/output pairs</examples>
```

XML also works as format indicators:

```xml
<smoothly_flowing_prose>Write report sections here</smoothly_flowing_prose>
<structured_data>JSON or tables here</structured_data>
```

XML outperforms markdown, JSON, or YAML for rule preservation in long prompts.

### Match Prompt Style to Desired Output

The formatting style in your prompt influences the agent's response. Include markdown formatting in your prompts when you want markdown output. Remove markdown from prompts if you want plain text output.

### Workflows

Break complex tasks into checkable steps:

```markdown
## Workflow
- [ ] Step 1: Analyze inputs
- [ ] Step 2: Generate plan
- [ ] Step 3: Validate plan
- [ ] Step 4: Execute
- [ ] Step 5: Verify output
```

### Feedback Loops

Validate → fix → repeat:

```markdown
1. Generate output
2. Run validator
3. If errors: fix and go to step 2
4. Only proceed when validation passes
```

### Degrees of Freedom

Match specificity to fragility:

| Task Type | Freedom | Style |
|-----------|---------|-------|
| Fragile operations | Low | Exact scripts, no modifications |
| Preferred patterns | Medium | Templates with parameters |
| Context-dependent | High | Principles and heuristics |

## Action Bias Templates

### Proactive (Default to Action)

```xml
<default_to_action>
By default, implement changes rather than only suggesting them. If the user's intent is unclear, infer the most useful likely action and proceed, using tools to discover any missing details instead of guessing. Try to infer the user's intent about whether a tool call is intended or not, and act accordingly.
</default_to_action>
```

### Conservative (Research First)

```xml
<do_not_act_before_instructions>
Do not jump into implementation or change files unless clearly instructed. When the user's intent is ambiguous, default to providing information, doing research, and providing recommendations rather than taking action. Only proceed with edits when the user explicitly requests them.
</do_not_act_before_instructions>
```

## Overengineering Prevention

Agents tend to overengineer. Include this when needed:

```markdown
Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.

Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.

Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.

Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow DRY.
```

## Naming (for Skills)

**Gerund form (verb + -ing):** `writing-skills`, `testing-code`, `debugging-errors`

**Name by action or insight:** `condition-based-waiting` not `async-helpers`

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Verbose explanations | Agent knows basics - omit |
| Multiple valid approaches | Pick one default, escape hatch for edge cases |
| Vague triggers | Specific symptoms: "tests flaky", "race condition" |
| Deeply nested references | Keep one level deep from main file |
| Windows paths | Always forward slashes |
| Aggressive language | Lead with context; reserve imperatives for true boundaries |

## Anti-Rationalization

For discipline-enforcing directives, anticipate excuses:

```markdown
## Red Flags

These reasons don't justify skipping the process:
- "This is simple enough to skip"
- "I already tested manually"
- "The spirit not the letter"
- "This case is different"
```

## Testing Directives

1. **Baseline:** Run the scenario without the directive, document failures
2. **Apply:** Add directive, verify compliance
3. **Iterate:** Find new loopholes → add counters → re-test

## Long-Running Tasks

For multi-context-window workflows and state management across sessions, see `long-running-state-patterns.md` in this directory.

## Graphviz (for Process Flows)

See `graphviz-conventions.dot` for flowchart style guide.

**Use flowcharts for:** Non-obvious decisions, process loops, "when to use A vs B"

**Don't use for:** Reference material (use tables), linear steps (use lists)