AGENTS.md Authoring Skill

AGENTS.md Authoring

Conventions for AGENTS.md files. Omissions intentional. All authored content MUST follow the Authoring rules in your system prompt (Authoring section).

Core Concept

AGENTS.md is a "README for agents": a predictable place for AI coding agent context. Supported by OpenAI Codex, Google Jules, Cursor, VS Code, GitHub Copilot, Devin, Windsurf, OpenCode, Aider, and others.

Writing Style

Prefer dense prose over multi-header structures. Collapse related constraints into single paragraphs. Use bullet lists only for genuine enumeration. Screenshot test: if removing a header and merging its content into the preceding section loses nothing, the header was unnecessary.

Essential Sections

Cover these areas (not necessarily as separate sections):

Constraints (dos/don'ts): Be nitpicky; clear guidelines prevent repeated mistakes.
Commands: File-scoped over project-wide; faster feedback.
Permissions: Explicit allow/ask lists prevent surprises.
Structure hints: A tiny index saves exploration time.
Example pointers: Real files beat abstractions.
When stuck: Escape hatch for uncertainty.
PR/commit checklist: Define "ready" explicitly.

Compressed example:

## Do

- use TypeScript strict mode
- default to small, focused diffs

## Don't

- no hard-coded colors; use design tokens
- no new dependencies without approval

## Commands

npm run tsc --noEmit path/to/file.tsx # type check single file
npm run eslint --fix path/to/file.tsx # lint single file

## Permissions

Allowed: read, type check, lint, single unit tests. Ask first: installs, push, deletes, full build.

## Structure

- routes: `src/App.tsx`
- components: `src/components/`
- design tokens: `src/lib/theme/tokens.ts`

## Examples

Copy: `src/components/UserForm.tsx` (forms). Avoid: `src/legacy/Admin.tsx` (class component).

## When stuck

Ask a clarifying question, propose a plan, or open a draft PR. Do not push speculative changes.

## PR checklist

lint + type check + tests green; diff small and focused; summary of what and why.

Skill Routing

Per-skill imperative triggers in AGENTS.md MUST use RFC 2119 keywords. Empirical testing shows skills relying on frontmatter alone trigger roughly half as often as skills with reinforcing AGENTS.md directives; softer phrasing produces measurably weaker compliance than MUST.

Skills used by both primary agents and subagents MUST live in AGENTS.md.
Skills used only by primary agents MUST live in opencode-primary-shared.md to avoid subagent context bloat.
The generic "check skills before acting" directive MUST NOT be duplicated across AGENTS.md and primary-shared; keep in AGENTS.md only.

Alternative: Instructions in opencode.json

Rules can load via the instructions field (globs + remote URLs); combines with AGENTS.md.

{
  "instructions": [
    "CONTRIBUTING.md",
    "packages/*/AGENTS.md",
    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
  ]
}

Nested AGENTS.md for Monorepos

Place AGENTS.md in subdirectories for package-specific rules. OpenCode traverses up from the working directory to the git worktree root; closer files take precedence. Global rules in ~/.config/opencode/AGENTS.md apply across all sessions.

Context Engineering

Position sensitivity: critical rules at the top; checklists at the end. Middle content receives the least model attention (U-shaped attention curve).
Completeness without bloat: terse rules, compressed examples, no filler.
Subtraction test: periodically remove rules and test whether behavior degrades. Rules that survive removal were noise; removing them improves signal density.

Rule Writing

Use RFC 2119 keywords (MUST, MUST NOT, SHOULD, SHOULD NOT, MAY). LLMs parse these as strict requirement levels, producing measurably higher compliance than softer phrasing.

MUST / SHALL: absolute requirement
MUST NOT / SHALL NOT: absolute prohibition
SHOULD / SHOULD NOT: strong preference; exceptions require justification
MAY: truly discretionary; usually omit instead
Constraint + consequence. Bad: "Don't commit to main." Good: "MUST NOT commit directly to main; use feature branches and PRs."
Specific over vague. Bad: "Be careful with error handling." Good: "All async functions MUST have try/catch; unhandled rejections crash the process."
Declarative for dense constraints. Stacking multiple imperative chains ("when X, don't do Y; also don't Z unless W") is measurably more fragile than flat declarative statements ("X: disabled. Y: required."). Use RFC 2119 imperatives for individual rules; prefer declarative state-setting for multi-condition constraint lists and configuration-like blocks.

Antipatterns

Repeated rules across files: single authoritative location.
Vague adjectives: replace with concrete criteria or examples.
Prohibitions without alternatives: include the correct approach.
Restating structural enforcement: if denied via permissions, skip the prose rule.
Duplicated routing: document delegation in one location (Agents section is authoritative).
Unscoped delegation: AGENTS.md is inherited by ALL agents. Delegation directives MUST scope to primary agents; otherwise subagents receive directives to delegate to agents they cannot invoke.

Validation Checklist

[ ] Each constraint has a consequence
[ ] Commands copy-pasteable; file-scoped where possible
[ ] Examples reference real files
[ ] "When stuck" guidance included
[ ] Skill routing directives use RFC 2119 keywords
[ ] Skill routing scoped correctly (primary-only skills in primary-shared)

Agent Skills: AGENTS.md Authoring

Install this agent skill to your local

Skill Files