Skills

Skills are Markdown files with YAML frontmatter that define agent capabilities. Agents discover and load skills dynamically at runtime.

Skill format

Skills follow the agentskills.io format:

---
name: web-search
description: Search the web and summarize results
license: MIT
compatibility:
  - openwalrus
tags:
  - search
  - web
allowed_tools:
  - bash
  - read
  - write
---

When asked to search the web, use the `bash` tool to run:

\`\`\`bash
curl -s "https://api.search.example/search?q={query}"
\`\`\`

Parse the JSON response and summarize the top results.

Directory

Skills live in ~/.openwalrus/skills/. Drop a .md file in this directory and it's available to all agents.

Discovery tools

Agents access skills through two tools:

search_skill

Search skills by tag or keyword:

{
  "name": "search_skill",
  "parameters": {
    "query": "web search"
  }
}

Returns matching skills with names and descriptions.

load_skill

Load a skill's instructions into the agent's context:

{
  "name": "load_skill",
  "parameters": {
    "name": "web-search"
  }
}

The skill's body is injected into the agent's system prompt, and its allowed_tools are made available.

How it works

1. SkillHandler indexes all skills in the skills directory by tags
2. Agents call search_skill to find relevant skills
3. Agents call load_skill to inject the skill instructions
4. The skill's allowed_tools become available for that session

This approach keeps agents lightweight — they only load the skills they need.

What's next

• MCP integration — connect external tool servers
• Built-in tools — filesystem and shell access
• Hooks — how skills plug into the agent lifecycle