# 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 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
- **Tools** — Total tool count (resolved)
- **Includes** — Number of included skills

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

---

## `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 (if any)
3. **Direct Tools** — Table with Tool, Source, Writes, Checkpoint columns
4. **MCP Servers** — Server name, transport, tool count, status (if any)
5. **Agent Skill Folders** — Folder paths (if any)
6. **Capability Summary** — Total tools, read-only, writes, checkpointable, side effects

---

## `agents skill tools`

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

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

### Arguments

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

### Options

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

### Examples

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

# Show as JSON
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 tool count and success message.

### Error Handling

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

---

## 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.