Skills Ecosystem
Relevant source files
The following files were used as context for generating this wiki page:
The Skills Ecosystem is a modular framework within Clawdbot that extends the agent's capabilities through specialized knowledge, workflows, and tools. Skills act as "onboarding guides" for specific domains, transforming a general-purpose agent into a specialized one equipped with procedural knowledge, such as API integrations, company-specific schemas, or multi-step domain workflows.
Sources: skills/skill-creator/SKILL.md:12-16
Architecture and Anatomy
Every skill is a self-contained package consisting of a mandatory SKILL.md file and optional bundled resources. The system uses a three-level loading system known as the Progressive Disclosure Design Principle to manage the LLM's context window efficiently.
Components of a Skill
| Component | Requirement | Description |
|---|---|---|
SKILL.md | Required | Contains YAML frontmatter (name, description) and Markdown instructions. |
scripts/ | Optional | Executable code (Python/Bash) for deterministic reliability. |
references/ | Optional | Documentation loaded into context only when needed. |
assets/ | Optional | Files used in output (templates, icons, boilerplate) not loaded into context. |
Sources: skills/skill-creator/SKILL.md:43-56, skills/skill-creator/SKILL.md:118-124
Progressive Disclosure Flow
The loading mechanism ensures that only the most relevant information occupies the context window.
The diagram shows how the system transitions from global metadata to specific instructions and finally to granular resources.
Sources: skills/skill-creator/SKILL.md:118-124
Skill Lifecycle and Management
The lifecycle of a skill involves initialization, validation, and loading into a workspace. Clawdbot maintains a strict precedence order when multiple versions of a skill exist across different directories.
Loading and Precedence
The system loads skills from four primary locations. If a skill with the same name exists in multiple locations, the one with the highest precedence is used.
- Workspace Skills (
skills/in workspace) - Highest Precedence - Managed Skills (typically
~/.clawdbot/skills) - Bundled Skills (internal to the application)
- Extra/Plugin Skills (configured via extra directories or plugins) - Lowest Precedence
Sources: src/agents/skills/workspace.ts:145-160
Skill Initialization Logic
New skills are created using the init_skill.py utility, which generates the directory structure and a template SKILL.md.
The sequence illustrates the automated process of setting up a standardized skill structure.
Sources: skills/skill-creator/scripts/init_skill.py:180-240
Execution and Gating
Skills are not automatically available; they must pass eligibility checks based on the environment and specific "gates" defined in their metadata.
Eligibility Checks
The buildWorkspaceSkillStatus function evaluates if a skill can be executed based on several requirements:
- Binaries: Checks if required executable files (e.g.,
ffmpeg) are in the system path. - Environment Variables: Verifies necessary API keys or tokens are set.
- OS Gating: Ensures the skill is running on a supported operating system (e.g.,
darwin,linux). - Allowlists: Respects configuration-level restrictions on bundled skills.
Sources: src/agents/skills.buildworkspaceskillstatus.test.ts:28-40, src/agents/skills/frontmatter.ts:98-120
Metadata Schema (Frontmatter)
Skills use YAML frontmatter to define their identity and requirements. A specialized metadata block within the YAML (using JSON5) provides deep configuration for the Clawdbot runtime.
---
name: my-skill
description: Triggers when doing X.
metadata: |
{
"clawdbot": {
"requires": {
"bins": ["ffmpeg"],
"env": ["PROVIDER_API_KEY"]
},
"os": ["darwin"],
"primaryEnv": "PROVIDER_API_KEY"
}
}
---
Sources: src/agents/skills/frontmatter.ts:88-120, src/agents/skills.buildworkspaceskillstatus.test.ts:34-38
CLI Interface
The skills CLI provides tools for users to inspect and debug the ecosystem.
| Command | Description |
|---|---|
clawdbot skills list | Lists all skills with their status (ready, disabled, or missing). |
clawdbot skills info <name> | Shows detailed path, source, and requirement status for a specific skill. |
clawdbot skills check | Provides a summary report of eligible vs. ineligible skills. |
Sources: src/cli/skills-cli.ts:220-270
Command Sanitization
When skills are exposed as user-invocable commands (e.g., slash commands), the system sanitizes their names to ensure compatibility with platforms like Discord. This involves converting the name to lowercase, replacing special characters with underscores, and truncating to a maximum of 32 characters.
Sources: src/agents/skills/workspace.ts:70-80
Conclusion
The Skills Ecosystem provides a robust, prioritized, and context-aware method for extending Clawdbot. By separating metadata from instructions and instructions from heavy resources, it maintains efficiency while allowing complex, deterministic logic to be packaged and deployed across different workspaces.