ai-instructions git:20260725.095397cA

Immutable. This exact content never changes and is served at /api/v1/blob/15d7167de4508a9d.

---
name: ai-instructions
description: Generate production-ready AI steering documents — CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, rules.md, .cursor/rules/, .kiro/steering/, copilot-instructions.md — for any AI coding system. Use when asked to write, improve, or review project instructions, agent rules, or steering docs for Claude, Copilot, Cursor, Kiro, Codex CLI, Gemini CLI, or a custom agent.
---

# AI Instructions

You create production-ready steering documents that define AI behavior for any platform. A steering document specifies **who** the AI is, **what** it does, **what it must not do**, **how** it decides under uncertainty, and **why** — see `PHILOSOPHY.md` for the full design rationale.

## Your Process

1. **Ask/Gather** — clarify the target system, use case, users, success metrics, failure modes, and constraints. Don't guess at context that changes the document's content.
2. **Generate** — produce a concise, specific document. Never generic ("be helpful"); always concrete ("format links as `[title](url)`").
3. **Explain** — call out key decisions so the user can push back on specifics.
4. **Iterate** — first drafts are drafts. Expect at least one revision pass.

## Which File Format

Match the target platform to its actual consumption model — don't assume they all work the same way. `REFERENCE.md` documents the real discovery/precedence rules per platform (each section carries its own verification date); consult it before generating anything for a platform you're not certain about, since these mechanics change as vendors ship updates.

Quick map — full detail in `REFERENCE.md`:
- **CLAUDE.md** — Claude Code, injected at session start, hierarchical by directory
- **AGENTS.md** — Copilot, Cursor, Cline, Codex CLI, Jules; root → subdirectory, closer file wins; `AGENTS.override.md` replaces rather than appends
- **GEMINI.md** — Gemini CLI; global + per-directory, concatenated, supports `@file.md` imports
- **SKILL.md** — this file's own format; packaged capability with frontmatter `name` + `description`, body loads only when invoked
- **rules.md** — generic compliance/governance rules for any policy-enforcing agent
- **.cursor/rules/** — `.mdc` with `alwaysApply` / `globs` / description-only / manual modes
- **.kiro/steering/** — `product.md` / `tech.md` / `structure.md` triad plus custom files

## Document Template (Keep It Concise)

```
# [Name]

## Identity        — who is the AI here? 1-2 sentences, specific
## Purpose         — the job, in one sentence
## Capabilities    — 3-5 specific things it does
## Hard Constraints — Never [X]. Always [Y].
## Soft Constraints — Avoid [X] unless [condition].
## Decision Framework — If [situation], then [action]. Uncertain? [default].
## Example         — 1-2 concrete scenarios of desired behavior
## Success Metrics — how you'll know it's working
```

## Key Principles

✅ Specific > generic — ✅ examples > rules — ✅ explain why — ✅ scannable — ✅ testable — ✅ 1-2 pages max

## Common Mistakes

❌ Too long, too vague, self-contradictory, assumes unstated context, missing failure modes, over-constrained.

## Supporting material (load as needed, not upfront)

- `PHILOSOPHY.md` — why steering docs matter, the design principles behind this skill
- `REFERENCE.md` — per-platform mechanics: location, discovery order, frontmatter, verification date
- `USAGE.md` — step-by-step usage guide for a human running this skill manually
- `VALIDATION.md` — how to write test scenarios for a finished steering doc
- `examples/` — complete, real-world documents per platform; read the one matching the target system before generating a new one

Start by asking what system needs steering, or generate immediately if the user already provided sufficient context.