212 lines
6.5 KiB
Markdown
212 lines
6.5 KiB
Markdown
# Capabilities
|
|
|
|
Capabilities are the extensions that make Waggle powerful: skills, plugins, MCP servers, workflow templates, hooks, and commands. This guide covers how to discover, install, and manage them.
|
|
|
|
## Capability Types
|
|
|
|
| Type | What It Is | Storage |
|
|
|------|-----------|---------|
|
|
| **Skill** | Markdown file that extends the agent's system prompt with domain knowledge and instructions | `~/.waggle/skills/*.md` |
|
|
| **Plugin** | Structured package with a manifest that adds tools and behaviors | `~/.waggle/plugins/` |
|
|
| **MCP Server** | Model Context Protocol server that provides external tools | Configured in settings |
|
|
| **Workflow Template** | Multi-step agent orchestration (e.g., research-team, review-pair, plan-execute) | Built into `@waggle/agent` |
|
|
| **Hook** | Event-driven callback (before/after tool calls, session start/end, etc.) | Registered in agent state |
|
|
| **Command** | Slash command (`/research`, `/draft`, etc.) | Built into `@waggle/agent` |
|
|
|
|
## Built-in Capability Packs
|
|
|
|
Waggle ships with 5 curated packs. Each pack bundles several skills that work together.
|
|
|
|
### Research Workflow
|
|
|
|
Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow.
|
|
|
|
### Writing Suite
|
|
|
|
Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`.
|
|
|
|
### Planning Master
|
|
|
|
Skills for task decomposition and execution. Includes `daily-plan`, `task-breakdown`, and the `plan-execute` workflow.
|
|
|
|
### Team Collaboration
|
|
|
|
Skills for coordination and communication. Includes `catch-up`, `status-update`, and `meeting-prep`.
|
|
|
|
### Decision Framework
|
|
|
|
Skills for structured decision-making. Includes `decision-matrix`, `risk-assessment`, and `retrospective`.
|
|
|
|
## Installing Packs
|
|
|
|
### From the UI
|
|
|
|
1. Navigate to **Capabilities** in the sidebar (or click the grid icon)
|
|
2. Click **Browse Packs**
|
|
3. Each pack shows its skills, install state (available / incomplete / complete), and description
|
|
4. Click **Install** to install all skills in the pack at once
|
|
5. Already-installed skills are skipped
|
|
|
|
### From the API
|
|
|
|
```bash
|
|
# Install the Research Workflow pack
|
|
curl -X POST http://localhost:3333/api/skills/capability-packs/research-workflow
|
|
|
|
# Install a single skill from the starter pack
|
|
curl -X POST http://localhost:3333/api/skills/starter-pack/draft-memo
|
|
```
|
|
|
|
## Installing Individual Skills
|
|
|
|
### From the Starter Catalog
|
|
|
|
1. Go to **Capabilities** > **Skills**
|
|
2. Browse by family: Writing & Docs, Research & Analysis, Decision Support, Planning & Organization, Communication, Code & Engineering, Creative & Ideation
|
|
3. Click **Install** on any skill
|
|
4. The skill is copied to `~/.waggle/skills/` and loaded immediately
|
|
|
|
### Creating Custom Skills
|
|
|
|
Skills are markdown files. Create a file in `~/.waggle/skills/`:
|
|
|
|
```markdown
|
|
# My Custom Skill
|
|
|
|
Instructions for the agent when this skill is active.
|
|
|
|
## When to Use
|
|
- Trigger conditions
|
|
|
|
## How to Respond
|
|
- Response format guidelines
|
|
- Quality standards
|
|
```
|
|
|
|
Or use the API:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3333/api/skills \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"name": "my-skill", "content": "# My Skill\n\nInstructions here."}'
|
|
```
|
|
|
|
## Marketplace
|
|
|
|
The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources.
|
|
|
|
### Searching
|
|
|
|
```bash
|
|
# Search by keyword
|
|
curl "http://localhost:3333/api/marketplace/search?query=research&limit=10"
|
|
|
|
# Filter by type
|
|
curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis"
|
|
```
|
|
|
|
Or use the `/marketplace search <query>` slash command in any workspace.
|
|
|
|
### Installing from Marketplace
|
|
|
|
```bash
|
|
# Install by package ID
|
|
curl -X POST http://localhost:3333/api/marketplace/install \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"packageId": 42}'
|
|
```
|
|
|
|
Or use `/marketplace install <name>`.
|
|
|
|
### Security Scanning
|
|
|
|
Every marketplace install goes through the **SecurityGate** scanner. Results determine whether the install proceeds:
|
|
|
|
| Severity | Action |
|
|
|----------|--------|
|
|
| CLEAN | Install proceeds immediately |
|
|
| LOW | Install proceeds, logged to audit trail |
|
|
| MEDIUM | Install proceeds with warnings in response |
|
|
| HIGH | Blocked unless `force=true` (override logged to audit) |
|
|
| CRITICAL | Always blocked, cannot override |
|
|
|
|
### Syncing the Catalog
|
|
|
|
```bash
|
|
# Sync from all configured sources
|
|
curl -X POST http://localhost:3333/api/marketplace/sync
|
|
```
|
|
|
|
Or use `/marketplace sync`.
|
|
|
|
## Trust Model
|
|
|
|
Waggle uses a multi-layer trust model:
|
|
|
|
1. **Source trust** -- starter-pack skills are trusted by default; marketplace and user-created skills get assessed
|
|
2. **Content analysis** -- heuristic scan for dangerous patterns (credential access, network calls, file system mutations)
|
|
3. **Risk level** -- low, medium, high, critical based on what the capability does
|
|
4. **Approval class** -- standard (auto-approve), review (log), force-override (user acknowledged risk), blocked
|
|
5. **Content hash** -- SHA-256 hash of each skill file, checked at startup to detect unauthorized modifications
|
|
|
|
### Audit Trail
|
|
|
|
Every install, uninstall, and security decision is recorded in the audit store. View it:
|
|
|
|
- **UI**: Capabilities > Cockpit > Trust Audit section
|
|
- **API**: `GET /api/audit/installs`
|
|
|
|
### Hash Verification
|
|
|
|
At startup, Waggle checks each installed skill's content hash against the stored hash. If a skill file was modified outside of Waggle, it is flagged in the hash status:
|
|
|
|
```bash
|
|
curl http://localhost:3333/api/skills/hash-status
|
|
```
|
|
|
|
## Plugins
|
|
|
|
Plugins are structured packages with manifests that can add tools and extend agent behavior.
|
|
|
|
### Installing a Plugin
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3333/api/plugins/install \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"sourceDir": "/path/to/my-plugin"}'
|
|
```
|
|
|
|
### Enabling / Disabling
|
|
|
|
```bash
|
|
# Enable
|
|
curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/enable
|
|
|
|
# Disable
|
|
curl -X POST http://localhost:3333/api/capabilities/plugins/my-plugin/disable
|
|
```
|
|
|
|
### Uninstalling
|
|
|
|
```bash
|
|
curl -X DELETE http://localhost:3333/api/plugins/my-plugin
|
|
```
|
|
|
|
## Viewing Capability Status
|
|
|
|
The **Cockpit** (accessible from the sidebar) shows a live dashboard of all capabilities:
|
|
|
|
- **Plugins**: name, state, tool count, skill count
|
|
- **MCP Servers**: name, state, healthy status, tool count
|
|
- **Skills**: name, content length
|
|
- **Tools**: total count (native + plugin + MCP)
|
|
- **Commands**: all registered slash commands
|
|
- **Hooks**: registered count, recent activity log
|
|
- **Workflows**: available templates with step counts
|
|
|
|
API equivalent:
|
|
|
|
```bash
|
|
curl http://localhost:3333/api/capabilities/status
|
|
```
|