agent-docs-writing

agent-docs

When to use

Use this skill when:

• Navigating the documentation structure to find relevant information
• Creating or updating agent documentation after changes
• Setting up documentation for a new module or package
• Understanding what documentation exists and where

Do NOT use when:

• Creating code or making technical changes (use coding skills)
• Looking for coding guidelines (use guidelines skill)

Documentation hierarchy

The documentation is organized in layers, from cross-project to module-specific:

Layer 1: .augment/ — Cross-project (identical in all repos)

.augment/
├── rules/          ← Always-active rules (coding, docker, scope, language, etc.)
├── commands/       ← Slash commands (fix-ci, create-pr, quality-fix, etc.)
├── skills/         ← Reusable skill definitions (coder, code-refactoring, etc.)
├── contexts/       ← Shared contexts about the agent system itself
├── templates/      ← Templates for features, roadmaps, contexts
└── guidelines/     ← Coding guidelines by language
    └── php/        ← PHP guidelines (controllers, eloquent, patterns, etc.)

Purpose: Universal agent behavior that applies to ALL projects and packages. Language: English. Key rule: This directory is identical across repos. Never add project-specific content here. Templates are the single source of truth for document structure — never store templates in agents/.

Layer 2: AGENTS.md — Project-level entry point

Located in the project root. Contains:

• Project description and tech stack
• Development setup (Docker, env files, Makefile targets)
• Testing conventions
• Quality tool configuration
• Links to ./agents/ for detailed docs

Purpose: First file an agent reads. Provides the full project context. Not every project has this — packages may only have ./agents/.

Layer 3: .github/copilot-instructions.md — Coding standards

Located in .github/. Contains:

• Architecture rules
• PHP coding standards
• Naming conventions
• ORM & database rules (Laravel example: Eloquent)
• API development rules