Skip to main content
Skills are markdown files that teach spaceduck new behaviors. Each skill is a SKILL.md file with YAML frontmatter (metadata) and a markdown body (instructions for the LLM). Skills are loaded at runtime without restarting the gateway.

​
How it works

When the gateway starts, it reads all SKILL.md files from configured paths, parses each one, runs the security scanner, and registers those that pass. Skills that fail the scan are rejected with a log entry explaining why.

​
SKILL.md format

A skill file has two parts: YAML frontmatter and a markdown body.
SKILL.md

​
Required fields

​
Optional fields (spaceduck extensions)

​
OpenClaw compatibility

spaceduck parses OpenClaw’s SKILL.md format natively. Unknown frontmatter fields (like tools, model, or provider) are silently preserved, never rejected. This means existing OpenClaw skills work out of the box.

​
Security scanner

Every skill is scanned before it enters the registry. The scanner checks four categories: Skills with critical findings are rejected. Skills with only warning findings are loaded but flagged in logs.
Dangerous tool references are downgraded from critical to warning when the skill declares an explicit toolAllow list, because tool scoping prevents the referenced tools from being available at runtime.
The scanner is static pattern matching only. It catches obvious attacks but not semantic ones (e.g. “read the file at ~/.ssh/id_rsa”). Tool scoping is the real enforcement layer. See Security for the full defense-in-depth model.

​
Tool scoping

Skills declare which tools they need via toolAllow. When a task runs with a skill, the agent loop only sees the tools that both the skill and the task permit. The merge logic is:
  • Allow lists: intersection (skill declares what it needs, task can further restrict)
  • Deny lists: union (both contribute)
A skill that declares toolAllow: [web_search] can never access the browser, file system, or shell, regardless of what its instructions say.

​
Memory attribution

When a skill writes to memory (via the memory_update result route), the memory record includes both taskId and skillId in its provenance. This enables:
  • Filtering memories by skill during recall
  • Cascading purge on skill uninstall (all memories written by the skill are deleted)
  • Auditing which skill produced which memories

​
First-party skills

spaceduck ships with three built-in skills in the skills/ directory: Each has a conservative budget and an empty toolAllow (no tool access).

​
Configuration

Skill settings live in spaceduck.config.json5 under the skills key. All settings hot-apply.
Setting autoScan: false disables the security scanner entirely. Only do this in development.