Skills

Skills are reusable markdown instruction files that SwarmClaw can discover automatically at runtime. Agents can pin specific skills as always-on guidance when they should stay in prompt, but ready local skills are otherwise discoverable by default.

SwarmClaw supports plain markdown skills and OpenClaw-style SKILL.md files with frontmatter, capabilities, install requirements, and executable dispatch metadata.

Discovery

SwarmClaw discovers skills from three layers:

bundled-skills/*/SKILL.md
<swarmclaw-home>/skills/*/SKILL.md
<project>/skills/*/SKILL.md

Later layers override earlier ones on name collision (project > workspace > bundled).

<swarmclaw-home> resolves from SWARMCLAW_HOME when set. Otherwise global installs default to ~/.swarmclaw, while local project installs default to <project>/.swarmclaw.

Each skill directory contains a SKILL.md file with YAML frontmatter:

---
name: Frontend Design
description: Expert frontend design guidelines and patterns
capabilities: [ui, frontend, design]
toolNames: [files, edit_file]
---

## Guidelines

- Use semantic HTML
- Follow accessibility best practices
- Prefer CSS Grid for layouts

The name and description fields appear in the SwarmClaw UI. The markdown body is used as guidance when the skill is loaded, and executable metadata can make the skill dispatch through existing tools at runtime.

Runtime Model

  • Ready local skills are discoverable by default
  • The agent editor's pinned skill list means always include this skill in prompt/context
  • Non-pinned skills stay available on demand through the use_skill runtime tool
  • manage_skills handles search, recommendation, attach, and install workflows
  • Shared skills remain reviewed artifacts. Conversation drafting and learned-skill promotion do not silently write into the shared library.

This keeps setup lighter: agents do not need every usable skill manually toggled on before they can discover and use it.

Learned Skills

SwarmClaw also keeps a separate learned-skill tier for autonomy hardening.

  • Learned skills are user and agent scoped by default rather than global
  • They can be acquired from repeated successful workflows or repeated external integration failures
  • Improvements land as shadow revisions first instead of overwriting the active revision directly
  • Repeated failures can auto-demote a learned skill until a later reflection or revision explicitly unlocks it again
  • Promotion into the shared reviewed skill library stays explicit

This lets agents get better at recurring work without turning the global skill library into an uncontrolled self-modifying prompt bank.

Pinning Skills to Agents

  1. Open an agent in the Agents sidebar
  2. Scroll to the Skills section
  3. Pin the skills that should stay always-on for that agent
  4. Save

When the agent runs:

  • Pinned skills can be injected directly into the agent's prompt as always-on guidance
  • Other discovered skills stay listed in the runtime skill section and can be selected on demand

Skill Runtime

SwarmClaw exposes a runtime skill surface so agents can resolve skills when they actually need them:

  • use_skill for runtime selection and execution
    • list
    • select
    • load
    • run
    • explain_blocker
  • manage_skills for install/attach/search/status workflows

Use load for guidance-only skills and run for executable skills that dispatch through an existing tool. Skill installs remain explicit and approval-gated.

Refreshing Skills

Click the Refresh button in the skills section to re-scan discovered skill directories. This picks up newly added or modified local skills without restarting the server.

Importing Skills by URL

Use Skills → Import via URL to fetch any remote markdown skill file.

  • Supported sources: http:// and https://
  • Max size: 2MB
  • OpenClaw SKILL.md frontmatter is parsed automatically

Example import URLs:

  • https://swarmclaw.ai/skills/openclaw-swarmclaw-bridge/SKILL.md
  • https://swarmclaw.ai/skills/swarmclaw-bootstrap/SKILL.md

Starter Skills

SwarmClaw now ships two ready-to-import skills:

  1. OpenClaw SwarmClaw Bridge

    • URL: https://swarmclaw.ai/skills/openclaw-swarmclaw-bridge/SKILL.md
    • Purpose: cross-chat delegation, task/schedule coordination, and memory + secret persistence between OpenClaw-backed runs.

  2. SwarmClaw Bootstrap

    • URL: https://swarmclaw.ai/skills/swarmclaw-bootstrap/SKILL.md
    • Purpose: clean install and validation workflow (providers, generation, heartbeat, delegation, secrets).

Creating Skills

To create a new workspace skill, use the SwarmClaw home directory for your install type:

  • Global install default: ~/.swarmclaw
  • Local project install default: <project>/.swarmclaw
  • Custom override: SWARMCLAW_HOME=/path/to/swarmclaw-home

Examples:

# Global install
mkdir -p ~/.swarmclaw/skills/my-skill
cat > ~/.swarmclaw/skills/my-skill/SKILL.md << 'EOF'
---
name: My Custom Skill
description: Description of what this skill does
---

Your skill instructions here...
EOF

# Local project install (run from the project root)
mkdir -p .swarmclaw/skills/my-skill
cat > .swarmclaw/skills/my-skill/SKILL.md << 'EOF'
---
name: My Custom Skill
description: Description of what this skill does
---

Your skill instructions here...
EOF

Then click Refresh in SwarmClaw to discover it.