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 add

Register a new skill from a YAML configuration file.

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

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

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

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

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

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

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

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

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

# 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

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

Composed Example

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.