In This Article
Introduction
OpenClaw's memory architecture includes TOOLS.md and SKILLS.md — files that enumerate the functional capabilities the agent can invoke. The LLM receives this list during each reasoning cycle, allowing it to decide which tools to call for a given task. Declarative definition keeps capabilities explicit and auditable. You can open these files and see exactly what your agent can do. No hidden capabilities. No magic.
This design is intentional. Many AI systems treat capabilities as implicit — the model "knows" what it can do from training, or capabilities are buried in code. OpenClaw makes them explicit. TOOLS.md and SKILLS.md are part of the agent's memory context. They're loaded into the prompt. The LLM reasons over them. When you add a tool or skill, you update the file. The agent sees the update on the next cycle. The capability surface is transparent, editable, and version-controlled. For security-conscious deployments, this is essential. You can audit. You can restrict. You can document. See SOUL.md for how these fit into the broader memory system.
Think of it like a restaurant menu. A chatbot has no menu — it might do anything, or nothing. You don't know. An OpenClaw agent has a menu: TOOLS.md and SKILLS.md. You can read it. You know exactly what the agent can order. If you don't want it to have access to execute_shell, you remove that from the menu. The agent can't order it. The analogy holds: the menu constrains behavior. The agent can only do what's on the menu. You control the menu.
TOOLS.md
TOOLS.md lists low-level tools: execute_shell, search_web, read_file, send_email. Each entry includes: name, description, parameters, and safety level. The agent uses this to understand what actions are available and when each is appropriate. For example, execute_shell might be marked "use for scripts, not arbitrary code" — the agent is instructed to prefer structured scripts over raw shell commands. The tool list is the agent's action palette. It can only do what's listed.
The format is flexible. You can add custom descriptions to steer behavior. "execute_shell: Run command in sandbox. Prefer .sh scripts over inline commands. Never run rm -rf. Use for automation, not ad-hoc execution." The agent receives this context. It influences tool selection. You're not just listing capabilities — you're instructing the agent on how to use them. This is prompt engineering at the capability level. Small changes to descriptions can significantly affect agent behavior.
Tools are the primitives. They're built into the OpenClaw runtime. execute_shell runs commands (in a sandbox, when configured). search_web queries a search API. read_file and write_file access the filesystem. send_email uses the configured email provider. The exact set depends on your OpenClaw version and configuration. What matters is that TOOLS.md is the canonical list. If it's not in TOOLS.md, the agent doesn't know about it. If you remove an entry, the agent loses that capability. You have full control.
SKILLS.md
SKILLS.md lists higher-level skills — modular packages that bundle multiple tools. A "Calendar" skill might expose: get_events, create_event, find_free_slots. Skills are loaded from ClawHub or local paths. SKILLS.md tells the agent which skills are installed and what they do. When you install a new skill, you (or the installer) update SKILLS.md. The agent sees the new capability on the next cycle. See skills explained and create a custom skill for more.
Skills extend the capability surface. A skill might wrap a third-party API (Google Calendar, Slack, Salesforce), add browser automation, or provide domain-specific logic. Each skill exposes one or more "actions" — functions the agent can call. SKILLS.md describes these actions. "calendar: get_events(date), create_event(title, start, end), find_free_slots(duration). Use for scheduling and availability checks." The agent reads this and knows when to use the calendar skill. Without SKILLS.md, the agent wouldn't know the skill exists.
Skill installation typically updates SKILLS.md automatically. If you install from ClawHub, the installer adds the appropriate entry. If you're building a custom skill, you add it manually. The format is consistent: skill name, description of capabilities, guidance on when to use. Good SKILLS.md entries improve agent performance. Vague entries lead to underuse or misuse. Invest in clear descriptions. The agent's reasoning quality depends on the quality of its context. SKILLS.md is part of that context.
Relationship
Tools are primitives; skills are compositions. TOOLS.md = what the runtime can do. SKILLS.md = what packages extend that. The agent reasons over both when planning actions. If a task requires "check my calendar," the agent looks for a calendar skill in SKILLS.md. If it needs "run a script," it looks for execute_shell in TOOLS.md. The two files together define the agent's capability surface.
The agent's reasoning loop: receive task → consult TOOLS.md and SKILLS.md → plan which tools/skills to use → execute → observe result → repeat. The files are loaded into context at the start of each cycle. The LLM doesn't have to "remember" what's available — it's right there in the prompt. This keeps the agent's model of its capabilities accurate. When you add a skill, the next task benefits immediately. No retraining. No fine-tuning. Just a file edit.
Some tasks require both. "Summarize my calendar for next week and email it to my team." Calendar skill for get_events. Email tool (or skill) for send_message. The agent reasons over both files to construct the plan. The separation — tools vs skills — reflects the architecture. Tools are core. Skills are optional extensions. But from the agent's perspective, they're all "things I can do." The files unify them into a single capability model.
The files live in your clawd directory. They're plain text. You can edit them with any editor. You can version them with git. You can diff them to see what changed. There's no binary format. No proprietary schema. Just Markdown. That's intentional. OpenClaw believes in transparency. If you want to understand what your agent can do, you read the files. If you want to change it, you edit the files. No magic. No hidden configuration.
Examples
# TOOLS.md
- execute_shell: Run command in sandbox. Use for scripts, not arbitrary code.
- search_web: Query search engine. Use for current information.
- read_file: Read file contents. Use for documents, configs.
- write_file: Write to file. Use for outputs, logs.
# SKILLS.md
- calendar: Google Calendar integration. get_events, create_event, find_free_slots.
- email: Gmail read/send. summarize_inbox, send_message, search_threads.
- slack: Slack integration. post_message, read_channel, create_channel.These examples show the level of detail. Each tool/skill has a one-line description and optional usage guidance. The agent uses this to decide "for 'check my schedule', I need the calendar skill's get_events." Richer descriptions improve accuracy. Sparse descriptions work but may lead to suboptimal tool selection. When in doubt, add more guidance.
Why It Matters
Transparent capability definitions improve security. You can audit what the agent can do. You can remove tools or skills you don't want. You can add descriptions that steer the agent's behavior ("use for scripts, not arbitrary code"). The files are in your clawd directory — you control them. No black box.
Security implications: after the 340 malicious skills incident, auditing capability definitions became critical. TOOLS.md and SKILLS.md give you a single place to review. What can my agent do? Everything listed there. What can it not do? Everything not listed. If you discover a skill has more capabilities than documented, that's a red flag. If you want to restrict the agent, remove the tool or skill from the file. The agent loses the capability immediately. No code changes. No redeployment. Edit the file. Done.
For compliance and audit trails, explicit capability definitions are valuable. "Our agent can do X, Y, Z. Here are the files that define that." Auditors can verify. Risk teams can assess. The alternative — implicit capabilities buried in code — is harder to reason about. OpenClaw's design prioritizes transparency. TOOLS.md and SKILLS.md are the foundation of that.
One more benefit: onboarding. When a new team member joins and wants to understand the agent, you point them to TOOLS.md and SKILLS.md. They read the files. They know what the agent can do. No need to trace through code. No need to ask "can it do X?" — they check the files. The capability surface is self-documenting. That reduces cognitive load for everyone who works with the agent.
Wrapping Up
TOOLS.md and SKILLS.md provide transparent, editable capability definitions. They're central to OpenClaw's memory architecture and security model. Edit them to add capabilities, restrict capabilities, or steer agent behavior. See skills explained and memory system for more. Your agent's capabilities are what you define. These files are where you define them.