ai-instructions git:20260928.8ead534A

Immutable. This exact content never changes and is served at /api/v1/blob/187f403061f17b20.

---
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. In particular, confirm which harness(es) the user actually runs before picking a file or location: "global" or "system" instructions mean that harness's user-level file (e.g. `~/.claude/CLAUDE.md` for Claude Code), never another vendor's.
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, loaded at session start, hierarchical by directory, supports `@file` imports
- **AGENTS.md** — cross-harness (Claude Code, Copilot, Cursor, Cline, Codex CLI, Jules); root → subdirectory, closer file wins; no standard global location. Prefer it as the single source of truth when a project uses more than one harness
- **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)

- `STEERING.md` — full per-format templates (CLAUDE.md, AGENTS.md, rules.md)
- `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.