Repository context

Choose the right steering files for your agents.

Browse practical patterns for AGENTS.md, PRODUCT.md, TECH.md, and tool-specific files. Each entry shows when to add it, what to include, and examples worth studying.

Install the skill Browse the catalog Read the GitHub README

Reusable skill

Install the catalog as an agent skill.

The ai-steering-files skill gives agents a compact workflow for choosing, writing, and auditing repo context files in any project.

View skill source

Skills CLI

npx skills add LVTD-LLC/ai-steering
Skills CLI docs

GitHub CLI

gh skill install LVTD-LLC/ai-steering ai-steering-files --agent codex --scope user
gh skill install docs

Steering file catalog

Each entry keeps the same structure: purpose, best use cases, required contents, reference links, and examples.

Agent-Agnostic Files

Start here for rules and context that should help every coding assistant work safely in the repo.

6 files

AGENTS.md

AGENTS.md

The shared operating manual every coding agent should read before changing the repo.

Use it for

repo-specific behavior that applies across tools · safe defaults, guardrails, and approval boundaries · exact commands agents can run with confidence · review, branch, and merge expectations

Should contain

  • concise project summary
  • preferred workflow
  • exact install, test, lint, build, and deploy commands
  • branch and PR policy
  • actions that need approval
  • rules agents should not bypass

Great examples

PRODUCT.md

PRODUCT.md

Product context that keeps implementation tradeoffs tied to users and outcomes.

Use it for

target users and use cases · the problem the product solves · major workflows and user journeys · business objectives and success criteria

Should contain

  • why the project exists
  • who it serves
  • what good looks like
  • what is in scope and out of scope
  • the outcomes that matter most

TECH.md

TECH.md

The technical source of truth for stack, commands, and implementation constraints.

Use it for

framework and library choices · runtime and package manager versions · build, check, test, and deploy commands · deployment targets, integrations, and APIs

Should contain

  • the canonical stack
  • supported commands
  • preferred libraries and patterns
  • external services and APIs
  • the constraints agents must respect

STRUCTURE.md

STRUCTURE.md

A repo map that helps agents put code, docs, and tests in the right place.

Use it for

top-level directory layout · naming conventions · import patterns · module boundaries and ownership lines

Should contain

  • a directory map
  • ownership boundaries
  • import rules
  • placement rules for new files
  • special-case folders that matter for the agent

VISION.md

VISION.md

Long-term direction, non-goals, and taste principles that should outlast individual specs.

Use it for

long-term product direction · non-goals · design and product taste · the future state the project is trying to create

Should contain

  • vision and durable constraints
  • what the project should become
  • what should not drift
  • success criteria at the level of outcomes, not implementation

DESIGN.md

DESIGN.md

A design-system source of truth for AI-generated UI changes.

Use it for

design tokens and theme choices · typography and spacing · layout rules · component patterns · accessibility expectations

Should contain

  • the visual language
  • spacing and type rules
  • layout constraints
  • component style preferences
  • UI patterns to avoid

Reusable Skills

Installable skills package this guidance so agents can reuse it across projects without loading the whole catalog.

1 files

skills/ai-steering-files/SKILL.md

ai-steering-files

An installable Agent Skill for choosing, writing, and maintaining repo steering files.

Use it for

creating AI steering files in a new or existing repo · auditing whether agent instructions are concrete enough · choosing between agent-agnostic, agent-specific, and path-scoped guidance · keeping reusable agent context portable across projects

Should contain

  • Agent Skills frontmatter with a searchable description
  • a practical workflow for inventorying existing steering files
  • a chooser table for common repo context files
  • quality checks for commands, paths, examples, and duplicate guidance

Agent-Specific Files

Add these when a tool needs its own syntax, memory model, or narrower workflow rules.

4 files

CLAUDE.md

CLAUDE.md

The Claude Code memory file for repo-specific instructions and workflows.

Use it for

Claude-specific guidance · repo conventions that should persist across Claude sessions · build/test/verify expectations for Claude · workflow notes that are useful in Claude Code

Should contain

  • project-specific instructions
  • code style and review rules
  • build and test commands
  • escalation boundaries
  • paths or workflows Claude should handle carefully

GEMINI.md

GEMINI.md

The Gemini CLI context file for repo instructions, commands, and response preferences.

Use it for

Gemini-specific instructions · repo conventions that should persist across Gemini sessions · project context and response preferences · custom commands or tool usage hints

Should contain

  • project-specific context
  • coding conventions
  • build/test/verify notes
  • files or folders Gemini should prioritize

.github/copilot-instructions.md

.github/copilot-instructions.md

Repository-wide instructions GitHub Copilot should apply when suggesting changes.

Use it for

Copilot instructions that apply across the repo · build/test/validation guidance · repo-specific coding standards · review and safety expectations

Should contain

  • how to build and test the repo
  • conventions and patterns to follow
  • constraints that should always be respected
  • any special validation steps

.cursor/rules/*.mdc

.cursor/rules/*.mdc

Path-scoped Cursor rules for workflows that need narrower guidance than a repo-wide file.

Use it for

file-specific or workflow-specific rules · path-scoped instructions · rule sets for certain parts of the repo · agent behavior that should not apply globally

Should contain

  • path or task scope
  • the conventions to follow in that scope
  • examples of good output
  • what should auto-apply vs stay manual

Writing checklist

Useful steering files are short, specific, and grounded in the repo.

Each item should make agent behavior easier to verify while it is editing.

  1. Define the file's job. Start with the scope and the intended reader.
  2. Prefer commands over vague guidance. Include exact install, test, lint, build, and deploy commands.
  3. Point to patterns worth copying. Name files and modules that show the preferred approach.
  4. Write down the boundaries. Spell out security, data, accessibility, performance, and product constraints.
  5. Keep one source of truth. Edit the data map once, then render the site and README from it.
  6. Review after real agent work. Update the files when agents repeatedly ask the same question or make the same mistake.