cleveragents-core/docs/reference/skill_cli.md

# Skill CLI Reference

The `agents skill` command group manages **skills** — reusable, composable collections of tools that can be registered, inspected, and attached to actors.

## Commands

| Command | Description |
|---------|-------------|
| `agents skill add` | Register a skill from a YAML config file |
| `agents skill remove` | Remove a registered skill |
| `agents skill list` | List registered skills with optional filters |
| `agents skill show` | Show full details for a registered skill |
| `agents skill tools` | List all tools provided by a skill (flattened) |
| `agents skill refresh` | Recompute tool flattening and sync MCP-backed skills |

---

## `agents skill add`

Register a new skill from a YAML configuration file.

```bash
agents skill add --config <FILE> [--update] [--format <FORMAT>]
```

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--config` | `-c` | Path to the skill YAML configuration file (required) |
| `--update` | | Allow overwriting an existing skill registration |
| `--format` | `-f` | Output format: `rich`, `json`, `yaml`, `plain`, `table` (default: `rich`) |

### Examples

```bash
# Register a new skill
agents skill add --config examples/skills/single-tool.yaml

# Update an existing skill
agents skill add --config examples/skills/single-tool.yaml --update

# Register and output as JSON
agents skill add --config my-skill.yaml --format json
```

### Rich Output

On success, the command prints a **Skill Registered** panel showing:
- Name, Description, Config path
- Includes list (if any)
- Direct tools with source, writes, and checkpoint columns
- MCP servers (if any)
- Capability summary (total tools, read-only, writes, checkpointable, side effects)
- Success message with tool count

### Error Handling

- **File not found**: Prints config file path and aborts.
- **Schema validation error**: Prints Pydantic validation details and aborts.
- **Duplicate skill**: Prints the existing name and suggests `--update`.

---

## `agents skill remove`

Remove a registered skill by its namespaced name.

```bash
agents skill remove <NAME> [--yes] [--format <FORMAT>]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `NAME` | Namespaced name of the skill to remove (e.g. `local/file-reader`) |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--yes` | `-y` | Skip confirmation prompt |
| `--format` | `-f` | Output format (default: `rich`) |

### Examples

```bash
# Remove with confirmation prompt
agents skill remove local/file-reader

# Remove without confirmation
agents skill remove local/file-reader --yes
```

### Rich Output

On success, the command prints a **Skill Removed** panel showing:
- Name of removed skill
- Number of tools removed from registry
- Number of MCP connections closed
- Dependency check (if other skills include the removed skill)

---

## `agents skill list`

List registered skills with optional namespace and source filters.

```bash
agents skill list [--namespace <NS>] [--source <SRC>] [--format <FORMAT>]
```

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--namespace` | `-n` | Filter by namespace (e.g. `local`, `remote`) |
| `--source` | | Filter by tool source type: `mcp`, `agent_skill`, `builtin`, `custom` |
| `--format` | `-f` | Output format (default: `rich`) |

### Examples

```bash
# List all skills
agents skill list

# List skills in a specific namespace
agents skill list --namespace local

# List only MCP-backed skills
agents skill list --source mcp

# List as JSON for scripting
agents skill list --format json
```

### Rich Output

Produces a table with columns:
- **Name** — Namespaced skill name
- **Description** — Skill description (truncated if long)
- **Tools** — Total tool count (direct, not flattened)
- **Includes** — Number of included skills
- **Sources** — Tool source types (comma-separated)

Followed by a **Summary** panel with total counts and a success message.

### JSON/YAML Output

Structured output includes `capability_summary` field with:
- `total_tools` — Total flattened tool count
- `read_only_tools` — Number of read-only tools
- `write_tools` — Number of tools that perform writes
- `checkpointable_tools` — Number of checkpointable tools
- `has_side_effects` — Boolean indicating side effects

---

## `agents skill show`

Show full details for a registered skill.

```bash
agents skill show <NAME> [--format <FORMAT>]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `NAME` | Namespaced name of the skill to show |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--format` | `-f` | Output format (default: `rich`) |

### Examples

```bash
# Show skill details
agents skill show local/file-reader

# Show as YAML
agents skill show local/file-reader --format yaml
```

### Rich Output

Prints multiple panels:
1. **Skill Details** — Name, Description, Config path, Created/Updated timestamps
2. **Includes** — List of included skills with tool counts (if any)
3. **Direct Tools** — Table with Tool, Source, Writes, Checkpoint columns
4. **MCP Servers** — Server name, transport, tool count, status (if any)
5. **Capability Summary** — Total tools (flattened), read-only, writes, checkpointable, side effects
6. **Referenced By** — Skills and actors that reference this skill (if any)

### JSON/YAML Output

Structured output includes `capability_summary` field with aggregated capability metrics across all resolved tools (including those from includes).

---

## `agents skill tools`

List all tools provided by a skill, including tools from included skills (flattened, de-duplicated).

```bash
agents skill tools <NAME> [--refresh] [--format <FORMAT>]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `NAME` | Namespaced name of the skill to resolve tools for |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--refresh` | | Re-scan Agent Skills discovery paths before resolving |
| `--format` | `-f` | Output format (default: `rich`) |

### Examples

```bash
# Show flattened tool list
agents skill tools local/composed-skill

# Refresh Agent Skills discovery before showing tools
agents skill tools local/devops --refresh

# Show as JSON with capability summary
agents skill tools local/composed-skill --format json
```

### Rich Output

Produces a table with columns:
- **Tool** — Tool name
- **Source** — Source type (builtin, mcp, agent_skill, inline)
- **From Skill** — Which skill contributed the tool (or "(direct)")
- **Read-Only** — Whether the tool is read-only
- **Writes** — Whether the tool writes
- **Checkpoint** — Whether the tool supports checkpointing

Followed by a **Summary** panel with:
- Total tool count (flattened)
- Tools from includes vs. direct
- Capability summary (read-only, writes, checkpointable counts)

### JSON/YAML Output

Structured output includes:
- `skill_name` — The queried skill name
- `tools` — Array of resolved tool entries with metadata
- `capability_summary` — Aggregated capability metrics

### Error Handling

- **Skill not found**: Prints error and aborts.
- **Circular includes**: Detects cycles and prints the cycle path.

---

## `agents skill refresh`

Recompute tool flattening and synchronize MCP-backed skills with their servers. This command triggers:

1. **Tool flattening recomputation** — Re-runs the resolution algorithm to pick up changes in included skills
2. **Agent Skills discovery** — Re-scans configured Agent Skills paths for new or updated folders
3. **MCP server sync** (when MCP adapter is available) — Re-enumerates tools from MCP servers

```bash
agents skill refresh <NAME> [--format <FORMAT>]
agents skill refresh --all [--format <FORMAT>]
```

### Arguments

| Argument | Description |
|----------|-------------|
| `NAME` | Namespaced name of the skill to refresh (mutually exclusive with `--all`) |

### Options

| Flag | Short | Description |
|------|-------|-------------|
| `--all` | | Refresh all registered skills |
| `--format` | `-f` | Output format (default: `rich`) |

### Examples

```bash
# Refresh a single skill
agents skill refresh local/devops-toolkit

# Refresh all skills
agents skill refresh --all

# Refresh with JSON output
agents skill refresh local/linear-tracker --format json
```

### Rich Output

For a single skill, prints a **Skill Refreshed** panel showing:
- Name
- Total tools (flattened count)
- Number of includes
- MCP servers count and sync status
- Agent Skills count
- Capability summary (read-only, writes, checkpointable)

For multiple skills (`--all`), prints a table with:
- Name
- Tools count
- Includes count
- MCP count
- Status (✓ or ✗)

Followed by an error panel if any skills failed to refresh.

### JSON/YAML Output

Structured output includes:
- `refreshed` — Number of skills processed
- `agent_skills_refreshed` — Boolean indicating if Agent Skills discovery ran
- `skills` — Array of refresh results with capability summaries
- `errors` — Array of error messages (if any)

### Error Handling

- **Skill not found**: Prints error and aborts (single skill mode)
- **MCP sync failure**: Skill is marked with error status but command continues
- **Missing arguments**: Requires either `<NAME>` or `--all`
- **Conflicting arguments**: Cannot specify both `<NAME>` and `--all`

### Refresh Side Effects

**Tool Flattening Cache:**
- The flattening algorithm is deterministic and stateless
- Each `refresh` call recomputes the full tool set from scratch
- No persistent cache is maintained — results are computed on-demand

**Agent Skills Discovery:**
- Re-scans directories configured in `skills.agent_skills_paths`
- Discovers new `.agent-skill/` folders or updated metadata
- Tools are registered in the in-memory Tool Registry
- Previous Agent Skills tool registrations are **not** automatically removed

**MCP Server Synchronization:**
- When MCP adapter integration is available, `refresh` re-enumerates tools from active MCP servers
- Picks up new tools added since skill registration
- Removes tools that are no longer exposed by the server
- Does **not** restart MCP server processes — only queries current tool list

**Recommended Use Cases:**
- After adding/removing includes in a skill's YAML config
- After adding new Agent Skills folders to discovery paths
- After MCP server tool updates (e.g., plugin upgrades)
- Before critical plan execution to ensure tool set is current

---

## Output Formats

All skill commands support the `--format` flag with the following options:

| Format | Description |
|--------|-------------|
| `rich` | Full Rich rendering with panels, tables, colors (default) |
| `json` | Machine-readable JSON output |
| `yaml` | Structured YAML output |
| `plain` | Plain text without formatting |
| `table` | Tabular output |

Structured formats (`json`, `yaml`) produce machine-parseable output suitable for piping to `jq`, `yq`, or other tools.

---

## Skill YAML Configuration

Skills are defined in YAML files. See `docs/schema/skill.schema.yaml` for the full schema.

### Minimal Example

```yaml
name: local/file-reader
description: "Basic file reading operations"
tools:
  - name: builtin/read_file
  - name: builtin/list_directory
```

### Composed Example

```yaml
name: local/git-github
description: "Git operations and GitHub integration"
tools:
  - name: builtin/shell_execute
includes:
  - name: local/file-reader
mcp_servers:
  - name: github
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    tool_filter:
      include: [create_issue, list_issues]
```

See `examples/skills/` for more configuration examples.