docs: update the capabilities and connectors guides for this edition (P2.4)

Remove KVARK enterprise connectors, the 120+ package count and the
curl examples, which no longer work without the session token. Describe
Skills Hub, the marketplace scan as the code applies it, MCP Hub, the
30 native connectors, the approval modes, and the messaging channels
with the whatsapp-web.js warnings and browser download.
This commit is contained in:
shumeiko.it
2026-11-01 01:58:42 +01:00
parent eca050328b
commit 834096146e
2 changed files with 144 additions and 352 deletions

View File

@@ -1,211 +1,100 @@
# Capabilities
# Skills, plugins and the marketplace
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.
Capabilities extend what the agent knows and can do. This guide covers the kinds of capability,
how to install them and how Waggle checks them.
## Capability Types
Most of the screens below appear at the **Everything** interface level (Settings → General).
| 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` |
## Kinds of capability
## Built-in Capability Packs
| Kind | What it is | Where it lives |
|---|---|---|
| Skill | A Markdown file with instructions and domain knowledge, added to the agent's prompt when active | `<data>/skills/*.md` |
| Plugin | A package with a manifest that adds tools and skills | `<data>/plugins/` |
| MCP server | A Model Context Protocol server that gives the agent external tools | Settings, MCP Hub |
| Workflow | A multi-agent recipe, such as `research-team`, `review-pair` or `plan-execute` | Built in, or created with `/workflow` |
| Command | A slash command such as `/research` or `/draft` | Built in ([reference](../reference/commands.md)) |
Waggle ships with 5 curated packs. Each pack bundles several skills that work together.
## Starter skills and capability packs
### Research Workflow
Waggle ships with starter skills in seven families: Writing & Docs, Research & Analysis,
Decision Support, Planning & Organization, Communication, Code & Engineering, and Creative &
Ideation. Install them one by one in **Skills Hub**, or as packs:
Skills for investigation and synthesis. Includes `research-synthesis`, `explain-concept`, and the `research-team` multi-agent workflow.
| Pack | Skills |
|---|---|
| Research Workflow | `research-synthesis`, `explain-concept`, `research-team` |
| Writing Suite | `draft-memo`, `compare-docs`, `extract-actions` |
| Planning Master | `daily-plan`, `task-breakdown`, `plan-execute`, `decision-matrix` |
| Team Collaboration | `catch-up`, `status-update`, `meeting-prep`, `review-pair` |
| Decision Framework | `decision-matrix`, `risk-assessment`, `retrospective` |
### Writing Suite
Installing a pack skips skills that are already installed. The "Team Collaboration" pack is a
set of skills for working with other people; it does not need team mode.
Skills for document creation and editing. Includes `draft-memo`, `compare-docs`, and `extract-actions`.
## Writing your own skill
### 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/`:
A skill is a Markdown file in `<data>/skills/` (by default `~/.waggle/skills/`). Optional YAML
frontmatter gives it a name and other metadata:
```markdown
# My Custom Skill
---
name: weekly-report
description: Write the weekly status report in our format
---
# Weekly report
Instructions for the agent when this skill is active.
## When to Use
- Trigger conditions
## How to Respond
- Response format guidelines
- Quality standards
When asked for the weekly report:
- Start with the three most important changes.
- List risks with an owner each.
- Keep it under one page.
```
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."}'
```
You can also create and edit skills in **Skills Hub**. `/skills` lists the active skills in a
chat.
## Marketplace
The marketplace catalog contains 120+ packages across skills, plugins, and MCP servers from curated sources.
**Marketplace** lists skills, plugins and MCP servers from curated sources. Search it, read a
package's details and install it. `/marketplace search <query>` and
`/marketplace install <name>` do the same from a chat; `/marketplace sync` refreshes the catalog
from its sources.
### Searching
### Security scan
```bash
# Search by keyword
curl "http://localhost:3333/api/marketplace/search?query=research&limit=10"
Every marketplace install is scanned first for dangerous patterns, such as reading credentials,
unexpected network calls or destructive file operations. The result decides what happens:
# Filter by type
curl "http://localhost:3333/api/marketplace/search?type=skill&category=analysis"
```
| Severity | Result |
|---|---|
| Clean, low | The install proceeds |
| Medium | The install proceeds with warnings |
| High | Blocked unless you confirm that you accept the risk |
| Critical | Always blocked |
Or use the `/marketplace search <query>` slash command in any workspace.
Installs, uninstalls and security decisions are recorded in the install audit trail in
`waggle.db`.
### 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
```
If a skill or plugin you installed from the marketplace does not show up in the agent, restart
Waggle. The marketplace installer's reload request does not reach the running server yet.
## Plugins
Plugins are structured packages with manifests that can add tools and extend agent behavior.
A plugin is a directory with a manifest. Install one from the marketplace or from a local
directory, then enable or disable it. A disabled plugin stays installed but adds nothing to the
agent.
### Installing a Plugin
## MCP servers
```bash
curl -X POST http://localhost:3333/api/plugins/install \
-H "Content-Type: application/json" \
-d '{"sourceDir": "/path/to/my-plugin"}'
```
**MCP Hub** shows the installed Model Context Protocol servers with their state, lets you start,
stop, test and remove them, and installs new ones from its catalog or from a server you
describe yourself. Catalog installs go through the same security scan as the marketplace.
### Enabling / Disabling
## Trust checks
```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
```
- **Source**: starter skills are trusted; marketplace and your own skills are assessed.
- **Content scan**: the heuristic scan described above.
- **Approval**: capabilities that ask for risky actions go through the same approval rules as
any other tool call (Settings → Permissions).
- **Content hash**: Waggle records a SHA-256 hash of each installed skill and checks it at
startup, so a skill changed outside Waggle is flagged.