Agent Docs Authoring

Purpose

Keep instruction files small and decision-changing: AGENTS.md holds always-true rules and project facts; Skills hold repeatable procedures. The goal is the smallest context that produces the most correct decisions — every line must earn its place.

When to use

Existing-file preservation: an improvement request is not permission for a wholesale rewrite. Preserve existing sections, examples and user preferences; make targeted patches and review the full diff. Substantial deletion, merging or relocation needs an explicit restructuring request. Back up originals. Brevity guides new writing; it must not erase existing detail merely to reduce line count.

• Creating a project AGENTS.md or restructuring an existing one.
• Writing or revising any SKILL.md.
• Deciding where a piece of guidance belongs (rule vs skill vs docs vs nothing).
• Audizing an instruction file that has grown bloated, contradictory, or too long for small models to follow.

The golden rule (decide everything by this)

If it is always true        → Rule (inside AGENTS.md)
If it is a repeatable process → Skill (.agents/skills/<name>/SKILL.md)
If it describes the project → AGENTS.md
If it can be automated      → Tool/Script
If it requires product or business judgment → Keep human in loop

Mental model

                 AGENTS.md
        "Who am I working on?"
                 │
      ┌──────────┴──────────┐
   Rules                 Skills
"What must be true?"   "How do I do it?"
      │                     │
 Always active      Loaded when needed

There is no separate rules directory — rules live inside AGENTS.md.

The two-times-pain rule (anti-bloat law)

Anything that hasn't caused pain at least twice does not enter AGENTS.md or a skill.

• A bug that repeated → Rule/Skill. An architecture mistake that repeated → Rule. A process that repeated → Skill.
• "Might be needed someday" → Docs, not AGENTS.md.

Exception — proactive rules allowed without pain evidence for: security/secret handling, data-loss risks, privacy boundaries, and irreversible operations. These are written before the first incident, because the first incident is too expensive to wait for.

When unsure: "has this hurt twice — or is it a security/data-loss/irreversibility risk?" If neither, leave it out and revisit when it does.

Weak-model design principle (what changed this standard)

Instruction files are consumed by models that vary in strength, and a weak model (Flash-class) fails differently from a strong one: it does not lack instructions, it drifts where two instructions are near each other and must decide which one applies. So:

1. Fewer authorities, more absolutes. Ten hard invariants beat thirty nuanced principles with exceptions, examples, and cross-references.
2. Put the short invariants at the very top. Attention position matters; a "Runtime Contract — Read This First" block in the first 30 lines does more for weak models than thirty rules added lower down. Detailed sections are then only the operationalization of those invariants.
3. Check every new rule against existing ones. If a new rule can be read as re-enabling a behavior another rule forbids (e.g. "state the deliverable before touching anything" vs "planning is internal"), rewrite one of them. Contradiction, not absence, is the usual cause of drift.
4. Make conditions checkable, not aspirational. "Inspect the changed-file set; every file must trace to the request" beats "stay focused".
5. Guidelines are triggers, not invariants. Absolute numbers ("files must stay under 1000 lines") cause rule collisions (typo fix → forced split → "avoid unnecessary refactoring" violation). Phrase them as "when the task already involves this area, consider…".
6. Don't demand measurements the model can't take. "Estimate your token fill at 4 chars/token, act at 40/50/70%" is cognitive tax; "prefer targeted reads; compact when context visibly threatens reliability" is followable.
7. Prohibited-phrase lists work. For escape-hatch behaviors ("Should I proceed?"), listing the exact sentences is more effective than describing the category.

AGENTS.md structure (project file standard)

# AGENTS.md

## Project Identity          — what is this, in 2–3 sentences + pointer to spec
## Architecture              — diagram + layering rules ("frontend has no business logic")
## Tech Stack                — table: layer / location / stack
## Directory Map             — where the important things live
## Development Commands      — install, dev, test, build, lint, version
## Agent Behavior            — how the agent should act: don't assume requirements,
                               inspect existing code before inventing patterns, avoid
                               unnecessary refactoring, preserve behavior, report honestly
## Coding Standards          — indentation, naming, quotes, imports, exports, i18n
## Rules Priority            — Critical > Architecture > Development > Quality
## Change Protocol           — Understand → Inspect → Plan → Confirm → Modify → Verify → Summarize
## Available Skills          — table with When column (real skills only)
## Testing Strategy          — what verification exists, what is planned
## Deployment                — CI, releases, hosting
## Important Notes           — hidden traps, non-obvious decisions, things that caused bugs ONLY

Keep it tight. Every line must earn its place: if a future agent wouldn't act differently because of it, avoid adding it. For existing content, follow the preservation rule above instead of automatically deleting it.

Rules priority classes

• Critical Rules — cannot be violated (safety, trust, data loss, execution integrity).
• Architecture Rules — design constraints (how the system is shaped).
• Development Rules — coding preferences (style, tooling).
• Quality Rules — verification requirements.

AI-enabled systems

An AI-powered product gets an AI Safety rule set (Critical or Architecture): never fabricate results, separate collected facts from AI interpretation, treat LLM/AI output as untrusted data, validate before storage. An AI product without these will drift into hallucinated content.

When to create a rule

It applies everywhere, breaking it causes damage, or it represents project identity. When NOT to: task instructions (→ Skill), temporary decisions (→ chat), generic knowledge the model already has.

Rules vs skills — the table must not lie

The Available Skills section lists skills only. A rule is not a skill: listing commit-approval, language-of-response, or backup as "skills" suggests they're optional. Keep them as rules; keep skills as loadable workflows.

Skill anatomy

A Skill is a directory with one SKILL.md (YAML frontmatter + body). It teaches how to perform one specific task reliably — workflow, decision rules, common mistakes, verification.

.agents/skills/<name>/
└── SKILL.md
    (optional: references/, examples/, templates/, scripts/)

Frontmatter (required — this is how the skill triggers)

---
name: skill-name
description: When to use this skill and why. Include trigger phrases so the model
  auto-loads it. First sentence = when to use; rest = what it achieves.
---

Body sections (fixed order)

# Name — Project

## Purpose              — what the skill achieves, in one or two sentences
## When to use          — trigger conditions (repeatable, checkable)
## Preconditions        — what must already be true before starting (backup done? rebuilt?)
## Workflow             — numbered, executable steps (an agent follows these)
## Rules                — decision rules ("Use transaction when… Do not use transaction when…")
## Common mistakes      — gotchas; the highest-value section
## Validation           — how to prove it worked (commands, checks, end-to-end flow)

Skill design principles

• Single responsibility. One skill = one capability (create-api-endpoint, not full-stack-engineer-skill).
• Executable. Steps an agent can follow — never "write good code" as an instruction.
• Include decision rules. The best skills contain when/why choices, not just steps.
• Include gotchas. Project-specific traps beat generic advice every time.
• Always include Validation. A skill without validation is incomplete.
• Preconditions matter. A skill that assumes a backup was taken will get skipped backups; state the requirement explicitly.
• Trigger ownership: one primary owner per intent. For every common user intent, exactly one skill description should be the obvious primary match — zero ambiguous peers, any number of explicit companions (a capability skill plus a cross-cutting standard like design-principles may legitimately co-load; the bug is two skills both claiming to own the workflow). If two descriptions independently claim the same intent, narrow one, make one explicitly delegate to the other (if research is not decisive, invoke X), or merge only if they are actually the same capability.

When to create a skill

• The task repeats frequently (weekly pattern, not one-off).
• It requires domain knowledge the model can't know (your architecture, your rules).
• It has hidden failure points (migrations, data loss, rollback, index problems).

When NOT to create a skill

• Generic knowledge the model already has (write-clean-code).
• Simple always-true rules (→ AGENTS.md instead).
• One-time tasks (→ just do it in the chat).
• A skill-system misfire you have seen once. When a skill misfires (wrong or no skill loaded, two loaded together without a companion relationship, a delegation chain broke, or a skill fired correctly but its body caused drift), record it as a firing/ownership bug — do not add a skill or refactor in response. Only a repeated pattern reopens the architecture; single observations are runtime evidence to collect, not a design change.

Project continuity (recommended, every project)

Project history lives in the repo, not in the conversation (a chat ends and gets compacted):

roadmap.md          — status snapshot + what's implemented + known issues
decisions log       — why choices were made (docs/decisions/ or similar)
changelog           — user-visible changes per release

Example: an append-only session archive in roadmap.md — when a chat ends, its ID gets one row, so future forks see what was done without depending on any single conversation.

examples/ folder convention (every project)

An examples/ folder at a project root is assumed to be agent reference material — samples to understand patterns, not project code — unless the project's AGENTS.md declares another purpose.

If reference-only (default): normally listed in .gitignore (not shipped); read-only learning material; never copy code from them into production (deprecated APIs and prototype architecture leak that way).

If intentionally part of the product (SDK samples, user docs examples, test fixtures): the project AGENTS.md must explicitly declare the exception — then the folder is normal source, tracked and copyable.

Example SKILL.md (skeleton to copy)

---
name: example-task
description: Do X the project way. Use when the task mentions X, or when adding/changing Y.
---

# Example Task — <Project>

## When to use
- Adding a new <thing>.
- Extending existing <thing>.

## Workflow
1. Understand requirements.
2. Inspect existing <pattern>.
3. Create <artifact A>.
4. Create <artifact B> (keep in sync with A).
5. Add tests.
6. Run verification.

## Rules
- <A> must never be edited directly; use the script.
- Every <thing> requires <validation>.

## Common mistakes
- Editing only one of the two synced files.
- Skipping the backup.
- Forgetting to rebuild the shared package.

## Verification
pnpm typecheck
pnpm lint
<manual check of the affected flow>

Writing tips that apply to both

• AGENTS.md is an interface between human and agent — not documentation. Every section exists to change agent behavior.
• Use tables for stacks, skills, and rules with attributes (When/Risk) — agents scan them fast.
• Short rules beat emotional language. "Never commit without approval" outperforms "Violating this rule is a serious breach of trust." Constraints, not drama.
• Reference skills, don't duplicate them. AGENTS.md says "use /db-migration"; the skill holds the workflow.
• Examples are worth 100 instructions — every standard above carries a concrete example.

Validation (after writing or editing any instruction file)

1. Ask: "is this the smallest context that creates the most correct decisions?" For new writing, omit redundant explanation. For existing files, flag relocation/deletion opportunities without applying substantial restructuring unless requested.
2. Re-read every existing rule against the new one — can the new rule be misread as re-enabling or forbidding something the old rule decides? Fix the wording of whichever causes the collision.
3. For weak-model suitability: is the guidance checkable ("inspect changed-file set") rather than aspirational ("stay focused")?
4. Confirm trigger phrases for new skills so they load exactly when needed — narrow triggers, not "use for anything".
5. Run the trigger ownership test: for every common user intent, exactly one skill description should be the obvious primary match. If two compete, narrow one or make it delegate — a shared trigger is a design bug, not overlap tolerance.