Most agent setups start with a pile of useful local skills.
That pile usually makes sense to the person who built it. There is a skill for GitHub, one for writing, one for reminders, one for privacy filtering, one for making diagrams, one for checking session logs, one for working with canvases, one for creating new skills, and so on.
The problem shows up later, when a future agent has to decide what to do.
A local skill library answers the question, “What can this environment do?”
An AGENTS.md
file should answer a different question:
When should an agent use each capability, what should it read first, what tools are safe to call, and what boundaries should it respect?
That difference matters. A directory full of skills is an inventory. Agent-ready documentation is an operating map.
This tutorial uses an OpenClaw-style skill library as the worked example, but the same pattern applies to any local agent setup.
A common mistake is to document skills in filesystem order.
That gives you something like this:
- github
- writing-style-skill
- privacy-filter
- remind-me
- canvas
- skill-creator
- session-logs
That list is technically true, but it does not help an agent make decisions.
A better first pass groups skills by the work they enable:
## Capability map
### Development workflows
Use these when the user asks about code, repositories, issues, pull requests, debugging, or project maintenance.
- github: interact with GitHub through the `gh` CLI
- gh-issues: fetch issues, select candidates, delegate fixes, and open PRs
- node-inspect-debugger: debug Node.js processes
- python-debugpy: debug Python code
### Writing and publishing
Use these when the user asks for drafts, essays, social posts, newsletters, or style-sensitive writing.
- writing-style-skill: draft in the user's preferred voice
- blog-drafter: create blog drafts
- x-posts: optimize short-form posts and threads
### Safety and privacy
Use these when content may contain personal data, secrets, or sensitive context.
- privacy-filter: redact PII from text or files
- 1password: retrieve secrets through the approved CLI flow
### Personal automation
Use these when the user asks for reminders, home devices, calendar checks, or recurring background tasks.
- remind-me: create one-time reminders
- taskflow: coordinate longer detached jobs
- weather: check current weather and forecasts
This turns the library into a decision surface. The agent no longer has to infer that writing-style-skill
is relevant to an essay draft, or that privacy-filter
should be considered before sharing text externally. The map says so.
A capability map becomes much more useful when each section includes triggers.
Triggers are short descriptions of the user intent that should cause the agent to load a skill.
For example:
## Writing and publishing
Load `writing-style-skill` when the user asks to:
- draft an article, essay, email, talk abstract, or newsletter
- rewrite something in their voice
- adapt technical content for developers
- make a draft sound less generic
Load `x-posts` when the user asks to:
- write a post for X
- turn an idea into a thread
- improve a short social post for reach or clarity
Load `blog-drafter` only when the user explicitly wants a blog draft created.
The last line matters. Some skills only produce local context. Others take external action. blog-drafter
crosses that boundary because it creates a draft in a publishing system. The agent needs to know that this should not happen casually.
Good triggers are concrete. Bad triggers are vague.
Bad:
Use this for content.
Better:
Use this when drafting or revising long-form writing, especially when tone and structure matter.
Best:
Load `writing-style-skill` before drafting blog posts, essays, conference abstracts, newsletter sections, or public-facing technical explanations.
The best version tells the agent what the user might actually say.
Many local skills have their own SKILL.md
. An agent should not guess from the skill name alone. The root AGENTS.md
should tell the agent which file is authoritative.
Example:
## Skill rule
When a task matches a skill, read that skill's `SKILL.md` before taking action.
Do not rely only on the skill name or description. The skill file may include safety rules, required tools, local paths, examples, or external-action limits.
For a local OpenClaw skill set, this is especially useful because different skills have different operational shapes.
A writing skill might mostly contain tone rules and examples.
A GitHub skill might specify preferred gh
commands and review behavior.
A home automation skill might include device-specific constraints.
A privacy skill might define which data must be filtered before sharing.
The root file does not need to duplicate all of that. It needs to make skill mandatory and predictable.
Agent documentation should make one distinction very clear:
Reading, drafting, searching, and organizing are internal actions.
Sending, posting, publishing, deleting, buying, messaging, or changing real-world systems are external actions.
That boundary belongs near the top of AGENTS.md
.
Example:
## External action boundary
The agent may freely:
- read local files
- inspect skill documentation
- draft text
- run non-destructive local checks
- prepare changes for review
The agent must ask before:
- sending email or messages
- publishing posts
- creating public drafts
- deleting data
- changing account settings
- controlling physical devices
- spending money
For OpenClaw-style environments, this boundary keeps powerful skills usable without making them reckless. A github
skill that reads issues is different from one that opens a pull request. A blog
skill that drafts locally is different from one that creates a draft in an external service. A govee
or homeconnect
skill can affect the physical environment.
Write those distinctions down.
Agents are much better when they do not have to reconstruct your risk model from vibes.
A capability map should not only say what a skill does. It should say what the agent should avoid doing.
For example:
## Privacy and redaction
Use `privacy-filter` before sharing user-provided text outside the local workspace when it may contain:
- names
- addresses
- phone numbers
- email addresses
- account identifiers
- private messages
- internal business context
Do not paste raw private content into public channels or external tools unless the user explicitly approves it.
Or for GitHub:
## GitHub work
Use `github` for repository, issue, pull request, and CI work.
Safe without asking:
- inspect issues and PRs
- read CI logs
- check branch status
- prepare local patches
Ask before:
- opening a PR
- commenting publicly
- closing issues
- pushing branches to shared remotes
This is the part many local docs miss. They document how to use a tool, but not when to stop.
Some skills should run before others.
In the OpenClaw set, writing-style-skill
should load before drafting. privacy-filter
should run before sharing sensitive text externally. skill-creator
should load before changing skill files. github
should load before acting on GitHub state.
That can be expressed as simple sequencing rules:
## Sequencing rules
Before drafting public writing, load `writing-style-skill`.
Before creating or modifying a reusable skill, load `skill-creator`.
Before using private text in an external channel, consider `privacy-filter`.
Before taking GitHub action, load `github` and inspect the current repository state.
Before using a tool that affects the outside world, confirm the user intended that action.
These rules save agents from doing work in the wrong order.
A good AGENTS.md
does not need to cover every possible path. It should cover the paths where ordering matters.
Examples are often more useful than rules.
Here is a compact routing table:
## Routing examples
User asks: "Draft this as a technical blog post."
Use: `writing-style-skill`
Do: draft in the user's preferred voice
Do not: publish it anywhere
User asks: "Turn this into a blog draft."
Use: `writing-style-skill`, then `blog-drafter`
Do: prepare the content first
Ask before: creating the external draft, unless the user clearly requested that exact action
User asks: "Can you fix this GitHub issue?"
Use: `github`, possibly `gh-issues`
Do: inspect the issue, read the repo, make local changes, run tests
Ask before: opening a PR if the instruction was ambiguous
User asks: "Remember this workflow as a reusable skill."
Use: `skill-creator`
Do: create or update the skill through the approved skill workflow
Do not: hand-edit skill proposal state if the environment has a dedicated tool for that
User asks: "Share this private message in a public post."
Use: `privacy-filter`
Do: redact or summarize safely
Ask before: publishing or sending
The point is not to create a huge rules engine. The point is to give future agents enough examples to route the next request correctly.
A reusable skill should explain general behavior. Local environment details belong somewhere else.
For OpenClaw-style workspaces, that might mean:
SKILL.md -> reusable instructions
TOOLS.md -> local device names, account aliases, hostnames, personal setup notes
AGENTS.md -> workspace-level operating rules
MEMORY.md -> durable user and project context
This separation keeps skills portable.
A weather
skill can explain how weather lookup works. The local notes can say which city is usually relevant. A canvas
skill can explain how to present HTML on connected nodes. Local notes can say which node names exist in this setup.
That distinction is small, but it keeps a skill library from turning into a private config dump.
If a skill can send, post, delete, control, spend, or expose private data, say so in the capability map.
A practical format:
## High-risk skills
These skills can affect external systems or expose private data. Load their `SKILL.md` and confirm intent before using them for external action.
- blog-drafter: creates drafts in a publishing account
- imsg: can send iMessage/SMS
- work-slack: reads workplace Slack data
- gog/work-google: access personal or work Google data
- govee/homeconnect/sensibo/switchbot: control physical devices
- 1password: accesses secrets
This does not mean the skills are unsafe. It means they are powerful.
Agents do better with clear labels.
A useful AGENTS.md
should be short enough to read and strong enough to steer behavior.
A good structure looks like this:
## Role
You are working inside this workspace. Read local instructions before acting. Prefer existing skills and tools over inventing new workflows.
## Startup
Read:
- SOUL.md
- USER.md
- recent daily memory files
- MEMORY.md when in a direct private session
## Capability map
Group available skills by task:
- development workflows
- writing and publishing
- privacy and safety
- personal automation
- debugging and inspection
- media and presentation
- skill maintenance
## Skill
When a task matches a skill, read that skill's `SKILL.md` before acting.
## External action boundary
Internal work is allowed. External action requires clear user intent or confirmation.
## Safety rules
Protect private data. Prefer recoverable actions. Do not run destructive commands casually.
## Routing examples
Include examples of common user requests and the skills they should trigger.
## Local notes
Put machine-specific details in `TOOLS.md`, not in reusable skills.
That is enough to turn a pile of local skills into a working agent interface.
The file should change as the skill library changes.
When you add a new skill, add it to the capability map. When a tool gains external side effects, move it into the high-risk section. When an agent makes a routing mistake, add a small example that would have prevented it.
The best AGENTS.md
files are not long. They are current.
For developers building local agent systems, this is the real payoff: your skill library stops being something only you understand. It becomes a documented capability layer that future agents can read, reason over, and use correctly.
That is what agent-ready documentation is for.