Agent Docs

Overview

Agent Docs is an OpenClaw skill that provides a structured approach to documentation for AI agents. It focuses on how to organize and surface instructions so an agent can quickly understand a project without reading the entire repository. The documentation describes a Hybrid Context Hierarchy that divides content into three layers: Constitution, Reference, and Research. The goal is to make agent behavior more reliable, reduce wasted context, and ensure key constraints are always visible.

Why This Skill Exists

Large repositories can overwhelm a model. Agent Docs is designed to solve that problem by defining what to read first, what to read only when needed, and how to keep high value instructions close to the top of an agent's context window. The skill emphasizes that a small amount of carefully structured documentation can outperform a large unstructured prompt. It also provides guidance on how to keep instructions stable as the project evolves.

The Hybrid Context Hierarchy

The documentation is organized into three layers:

• Constitution: The most important rules and boundaries. These are high level constraints that must always be enforced. This layer includes requirements, safety rules, and absolute constraints that should never be violated.
• Reference: The core knowledge for the project. This includes the architecture, key workflows, critical commands, and decisions. Reference material is meant to be quickly accessible and reusable.
• Research: Optional or deep context that is only pulled when needed. This includes long design notes, deep historical context, and large reference materials.

The key idea is that each layer should be scoped to its purpose. Constitution content should be short and stable. Reference content should be comprehensive but organized for quick lookups. Research content can be large but should be clearly separated.

Recommended File Layout

The skill suggests a structured file layout that makes navigation predictable. Typical elements include:

• AGENTS.md at the repository root, which explains how an agent should approach the project.
• llms.txt or a similar index file that points to the most relevant documents.
• A doc map or index that lists key files by purpose.

This layout makes it easy to bootstrap an agent: read AGENTS.md first, then use the index to decide which reference sections to load. The documentation stresses that an agent should not blindly read everything. It should only load what is relevant to the current task.

Bootstrap Strategy

Agent Docs describes a bootstrapping strategy that starts with a short overview, then expands only if needed. The first pass should answer questions like: What is this project? Where is the code? What are the key commands? What are the constraints? If the agent needs more detail, it can follow links into reference or research material.

This approach helps avoid the "lost in the middle" problem, where important instructions are buried in long prompts. By always reading the constitution first and using an index to navigate, the agent reduces the chance of missing critical constraints.

Context Packaging and Chunking

The skill recommends that large documents be broken into small, well labeled chunks. Each chunk should have a clear scope and a short heading. This makes it easier for agents to fetch only the relevant sections. It also improves search and retrieval when using RAG systems.

A good chunking strategy includes:

• Headings that describe intent, not just topic.
• Short sections that can be loaded independently.
• Consistent naming so sections are easy to reference.

The documentation also suggests writing summaries or short descriptions at the top of each file. This lets an agent decide quickly whether to read the full file.

Guidance on Instructions

Agent Docs emphasizes explicit instruction writing. It advises using concrete verbs, precise file paths, and clear boundaries. It also encourages listing negative constraints such as "do not change this file" or "do not run destructive commands." By making constraints explicit, the agent is less likely to make dangerous changes.

The skill also notes that instruction wording should be stable. Frequent rewrites can confuse agent behavior. Instead, update instructions only when workflows change. Use versioning or change logs if needed.

Cross Linking and Discoverability

To keep documentation discoverable, the skill suggests using linkable sections and consistent anchors. If a document references another, include the path and a short summary of why it matters. This creates a map of information rather than a single long file.

An example pattern is to keep an index file that lists key documents with one sentence descriptions. The index acts as a directory for agents, allowing fast navigation without scrolling.

How This Relates to OpenClaw Skills

OpenClaw skills use SKILL.md as a canonical documentation file. The OpenClaw skill documentation emphasizes structured metadata and clear usage instructions. Agent Docs aligns with that by recommending explicit sections, clear constraints, and repeatable layouts. When building skills, use the same discipline: put core rules at the top, put usage instructions in a predictable section, and separate optional details into appendix style notes.

This makes it easier for other agents or reviewers to understand the skill, and it reduces ambiguity when an automation system runs the skill.

Example Application

Suppose you are documenting a code base. Start with AGENTS.md and include a short project summary, constraints, and top level commands. Then create a docs index that points to architecture, API, and operations guides. Each document should start with a short summary and include headings that match how a task is requested. If the agent is asked to build a feature, it can load the architecture doc and the relevant API doc without reading everything else.

If the project includes special rules, place them in the constitution section and reference them explicitly. This ensures the agent sees them early and consistently.

Troubleshooting and Maintenance

When an agent makes mistakes, the documentation should be adjusted rather than adding more unstructured text. The skill recommends identifying the missing instruction, placing it in the appropriate layer, and updating the index. Over time, this creates a stable documentation system that teaches agents what they need to know without overwhelming them.

Summary

Agent Docs provides a clear system for creating agent friendly documentation. Its Hybrid Context Hierarchy separates rules, reference material, and deep research. The recommended file layout and bootstrap strategy help agents find the right information fast. By using explicit instructions, consistent structure, and a strong index, teams can make agent behavior more reliable and reduce errors.