Files
claw-code/docs/bundled-skills-registry.md
T
clawdbot cd04270a17 feat(skills): implement bundled skills registry and skill chaining support (#3324)
- Add SkillOrigin::Bundled variant to support bundled skills registry
- Implement bundled_skill_root() function for discovering bundled skills
- Update skill discovery to include bundled skills from standard install paths
- Create example bundled skills (example-skill, chain-example)
- Add comprehensive tests for bundled skills discovery and metadata
- Bundled skills follow same directory structure as plugins
- Skills can now chain/invoke other skills using standard dispatch mechanisms
- Maintains backward compatibility with existing SkillsDir and LegacyCommandsDir
2026-10-13 01:05:22 +00:00

107 lines
3.4 KiB
Markdown

# Bundled Skills Registry and Chaining
## Overview
The bundled skills registry enables claw-code to include built-in skills with each release, similar to how bundled plugins work. This feature supports skill chaining, allowing skills to invoke and compose with other skills.
## Implementation
### Architecture
**Bundled Skills Root Discovery**: Skills are discovered from the following locations (in order of precedence):
1. `<exe_dir>/../share/claw/skills/bundled` — standard FHS install layout
2. `<exe_dir>/bundled-skills` — simple relocated layout
3. `CARGO_MANIFEST_DIR/bundled` — dev/source-tree fallback
4. Default fallback if above paths don't exist
The directory structure mirrors the plugin system:
```
rust/crates/commands/bundled/
├── example-skill/
│ └── SKILL.md
└── chain-example/
└── SKILL.md
```
### SkillOrigin Enum
A new `Bundled` variant was added to the `SkillOrigin` enum:
```rust
enum SkillOrigin {
SkillsDir, // User/project skills directories
LegacyCommandsDir, // Legacy /commands directories
Bundled, // Built-in bundled skills [NEW]
}
```
### Skill Discovery
The `discover_skill_roots()` function was updated to include bundled skills:
- Bundled skills are added to the discovery roots with `SkillOrigin::Bundled`
- They're loaded using the same mechanism as regular skills
- Bundled skills have origin metadata ("bundled") in JSON output
### Skill Chaining
Skills can invoke other skills through standard mechanisms:
1. **Slash Command Invocation**: A skill can document that it chains to another skill
```
/skill chain-example
```
2. **Tool-based Invocation**: Via the Skill tool or similar mechanisms
Skills marked as "bundled" indicate they're managed by the claw-code release and persist across upgrades.
## Example Bundled Skills
### `example-skill`
A simple demonstration skill showing the bundled skills feature.
### `chain-example`
An example showing how one skill can reference and chain to other skills (e.g., `example-skill`).
## Testing
Three new tests were added:
1. **`discovers_bundled_skills_from_binary_layout`**
- Verifies that `discover_skill_roots()` includes bundled skills
- Tests directory discovery logic
2. **`bundled_skills_have_correct_origin_metadata`**
- Confirms `SkillOrigin::Bundled` generates correct metadata
- Tests JSON output format
3. **`bundled_skills_are_included_in_json_output`**
- Verifies loaded bundled skills appear in JSON output
- Tests end-to-end loading flow
All tests pass with:
```bash
cargo test -p commands --lib
```
## Backward Compatibility
- Existing skill discovery paths unchanged
- `SkillsDir` and `LegacyCommandsDir` origins fully preserved
- No changes to skill file format or content
- Bundled skills are additive; they don't replace user/project skills
## Future Enhancement Points
1. **Bundled Skills Registry Sync**: Auto-sync bundled skills into a system registry (similar to plugins)
2. **Skill Dependency Resolution**: Automatic dependency discovery and loading
3. **Skill Versioning**: Track versions of bundled skills
4. **Skill Auto-Update**: Sync bundled skills on claw-code updates
## Related
- **Issue**: #3324 [Slice 2.2] Skills bundled registry & chaining
- **Plugin System**: `rust/crates/plugins/src/lib.rs` (bundled plugins reference implementation)
- **Commands Crate**: `rust/crates/commands/src/lib.rs` (implementation location)