magnus919_agent-skills/technical-documentation/references/agent-facing-docs.md

Agent-Facing Documentation

AGENTS.md Structure

Agent-facing docs have different requirements than human-facing docs. Agents read the entire file sequentially, so structure matters differently.

Required Sections

# Project Name — Agent Guidance

## Trigger Patterns

| User Says | What It Means |
|---|---|
| "Deploy this service" | Full deployment: build → configure → deploy → verify |
| "Check service status" | Status check with health endpoint verification |

## Loading Order

Specify which skills to load and in what order. Skills should be loaded explicitly,
not assumed.

\`\`\`python
skill_view('artifact-pyramids')    # 1. Output format
skill_view('deployment-methodology')  # 2. Methodology
\`\`\`

## Output Contract

Be explicit about what the agent produces and how to interpret it. If using
artifact pyramids, say so.

Skill Documentation

When documenting a skill for agent consumption:

Element	Required	Purpose
Trigger conditions	Yes	When does an agent know to load this skill?
Loading order	Yes	What to load first, what depends on what
Reference files table	Yes	What each reference is for and when to load it
Output contract	Yes	What format does the agent produce?
Pitfalls	Recommended	What commonly goes wrong?