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.

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

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

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

# 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

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

# 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

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.