Turn a local skill library into agent-ready documentation

A developer outlines a method for transforming a local skill library into agent-ready documentation. By grouping skills into a capability map with concrete triggers, agents can make better decisions about which tools to use and when. The approach turns a simple inventory into an operating map that improves agent autonomy and safety.

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 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. 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: php 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: 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. 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.