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.

Start with capabilities, not files

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.

Add triggers

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.

Document the first file to read

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 loading 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 loading mandatory and predictable.

Separate internal work from external action

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.

Capture tool boundaries inside each capability

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.

Include sequencing rules

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.

Give agents examples of correct routing

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.

Keep local notes out of shared skills

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.

Make safety boundaries visible, not buried

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.

Write the root AGENTS.md as an operating manual

A useful AGENTS.md should be short enough to read and strong enough to steer behavior.

A good structure looks like this:

# AGENTS.md

## 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 loading

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.

Treat AGENTS.md as a map, not a museum

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.