# ai-instructions

## What This Repo Is

A **prompt-based skill** — no code, no build system, no tests. All content is Markdown. It teaches any AI harness to generate steering documents (CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, rules.md, Cursor rules, Kiro steering, Copilot instructions).

This file is the repo's single instruction file: Claude Code, Copilot, Codex, and Cursor all read a root `AGENTS.md`. Don't add a `CLAUDE.md` — in Claude Code it would stop this file from loading.

## File Map

| File | Role |
|------|------|
| `SKILL.md` | Installable skill manifest — frontmatter + condensed master prompt; the entry point for agents |
| `STEERING.md` | Standalone master prompt for manual copy-paste; holds the per-format templates |
| `REFERENCE.md` | Per-platform mechanics (locations, discovery, precedence), each section with its own *Verified* date |
| `PHILOSOPHY.md` | Design principles behind steering docs |
| `USAGE.md` | Step-by-step guide for a human running the skill manually |
| `VALIDATION.md` | Test-scenario templates and pre-deploy checklist |
| `examples/` | One complete document per platform |

## Key Conventions

- **Harness-agnostic.** Core files (`SKILL.md`, `STEERING.md`, `PHILOSOPHY.md`, `USAGE.md`, `VALIDATION.md`) must not assume any one vendor's mechanics. Platform-specific behavior (e.g. Codex's `AGENTS.override.md`, `~/.codex/`) belongs only in its own `REFERENCE.md` subsection and its own example.
- **Token economy is a first-class constraint.** Prefer cutting over adding; the skill's value is density.
- **Show, don't tell.** Reach for a concrete example before adding a rule.
- **Specific > generic.** Flag vague guidance during edits.

## When Editing Content

- Platform facts in `REFERENCE.md` must come from the vendor's current docs. Update the section's *Verified* date only when you actually checked the source.
- `SKILL.md` and `STEERING.md` overlap by design (agent entry point vs. copy-paste prompt) — keep their format lists and principles in sync.
- New examples go in `examples/` and must be listed in `README.md` (both tables) and `USAGE.md`.
- A new platform needs: a `REFERENCE.md` section + Decision Matrix row, a line in `SKILL.md`'s quick map and `STEERING.md`'s Document Types, and an example.