33 KiB
Resource and Skill Management with CleverAgents
Overview
CleverAgents provides a powerful resource registry and skill management system that lets you track project assets (git checkouts, directories, containers, LSP servers, cloud resources) and define reusable tool collections (skills) that agents can use. This guide walks through the complete workflow with real output captured from a live installation.
Prerequisites
- CleverAgents installed (
pip install cleveragentsor from source withuv sync) - Python 3.12 or higher
What You'll Learn
- How to explore the 100+ built-in resource types
- How to register and inspect resources (git repos, directories, containers)
- How to filter resources by type and view them in multiple output formats
- How to create and manage skills from YAML config files
- How to compose skills that include other skills and MCP server integrations
- How to inspect skill tool inventories and capability summaries
Part 1: Resource Management
Step 1: Explore Available Resource Types
CleverAgents ships with 100+ built-in resource types covering git, filesystem, containers, cloud providers (AWS, GCP, Azure), databases, and LSP servers.
$ python -m cleveragents resource type list
Actual Output (truncated):
Resource Types (101 total)
┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name ┃ Kind ┃ Sandbox ┃ Inherits ┃ Built-in ┃ User-add… ┃
┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
│ git │ physical │ none │ │ yes │ yes │
│ git-checkout │ physical │ git_wor… │ │ yes │ yes │
│ git-branch │ physical │ none │ │ yes │ no │
│ fs-directory │ physical │ copy_on… │ │ yes │ yes │
│ container-instance│ physical │ snapshot │ │ yes │ yes │
│ lsp-server │ physical │ none │ │ yes │ yes │
│ aws-ec2-instance │ physical │ none │ cloud-co… │ yes │ no │
│ postgres │ physical │ transac… │ │ yes │ yes │
│ sqlite │ physical │ transac… │ │ yes │ yes │
│ ... │ ... │ ... │ ... │ ... │ ... │
└───────────────────┴──────────┴──────────┴───────────┴──────────┴────────────┘
What's Happening: The resource type registry is loaded from built-in YAML definitions. Each type specifies its kind (physical/virtual), sandbox strategy, inheritance, and whether users can add instances of it.
Step 2: Filter Resource Types with Regex
You can filter the type list with a regex pattern:
$ python -m cleveragents resource type list "git.*"
Actual Output:
Resource Types (10 total)
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Name ┃ Kind ┃ Sandbox ┃ Inherits ┃ Built-in ┃ User-add… ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ git │ physical │ none │ │ yes │ yes │
│ git-branch │ physical │ none │ │ yes │ no │
│ git-checkout │ physical │ git_work… │ │ yes │ yes │
│ git-commit │ physical │ none │ │ yes │ no │
│ git-remote │ physical │ none │ │ yes │ no │
│ git-stash │ physical │ none │ │ yes │ no │
│ git-submodule │ physical │ none │ │ yes │ no │
│ git-tag │ physical │ none │ │ yes │ no │
│ git-tree │ physical │ none │ │ yes │ no │
│ git-tree-entry │ physical │ none │ │ yes │ no │
└─────────────────┴──────────┴───────────┴──────────┴──────────┴─────────────┘
What's Happening:
The regex git.* matches all resource type names starting with "git", showing
the full git object model hierarchy that CleverAgents tracks.
Step 3: Inspect a Specific Resource Type
Get full details about a resource type including its CLI arguments and parent/child relationships:
$ python -m cleveragents resource type show git-checkout
Actual Output:
╭─────────────────────────────── Resource Type ────────────────────────────────╮
│ Name: git-checkout │
│ Description: A local git checkout (cloned repository or worktree). │
│ Inherits: (none) │
│ Inheritance Chain: (root type) │
│ Kind: physical │
│ Sandbox Strategy: git_worktree │
│ Built-in: yes │
│ User-addable: yes │
│ Handler: cleveragents.resource.handlers.git_checkout:GitCheckoutHandler │
│ CLI Arguments: │
│ --path (path, required) │
│ Path to the git checkout directory. │
│ --branch (string, optional) │
│ Branch to use (defaults to current HEAD). │
│ Parent Types: (none) │
│ Child Types: git, fs-directory, fs-file, devcontainer-instance, │
│ devcontainer-file │
╰──────────────────────────────────────────────────────────────────────────────╯
What's Happening:
The git-checkout type uses a git_worktree sandbox strategy, meaning
CleverAgents can create isolated git worktrees for safe code modifications.
It can have child resources of types git, fs-directory, fs-file, etc.
Step 4: Register a Git Repository Resource
Add a git checkout resource pointing to a local repository:
$ python -m cleveragents resource add git-checkout local/my-repo \
--path /path/to/your/repo \
--description "My project repository"
Actual Output:
Added resource: local/my-repo (id: 01KNKJY4X9K7ZDNEK7M6TKJTDG)
What's Happening:
The resource is registered in CleverAgents' SQLite database with a ULID
identifier. The local/ namespace indicates a user-defined resource (as
opposed to server-managed resources).
Step 5: List Registered Resources
$ python -m cleveragents resource list
Actual Output:
Resources (1 total)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ ID ┃ Name ┃ Type ┃ Status ┃ Kind ┃ Location ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ 01KNKJY4... │ local/my-repo │ git-checkout │ │ physical │ /app │
└──────────────┴───────────────┴──────────────┴────────┴──────────┴───────────┘
Step 6: Filter Resources by Type
$ python -m cleveragents resource list --type git-checkout
Actual Output:
Resources (1 total)
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┓
┃ ID ┃ Name ┃ Type ┃ Status ┃ Kind ┃ Location ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━┩
│ 01KNKJY4... │ local/my-repo │ git-checkout │ │ physical │ /app │
└──────────────┴───────────────┴──────────────┴────────┴──────────┴───────────┘
Step 7: Show Resource Details
$ python -m cleveragents resource show local/my-repo
Actual Output:
╭──────────── Resource Details ─────────────╮
│ Resource ID: 01KNKJY4X9K7ZDNEK7M6TKJTDG │
│ Name: local/my-repo │
│ Type: git-checkout │
│ Classification: physical │
│ Description: My project repository │
│ Location: /app │
│ Properties: │
│ path: /app │
│ Created: 2026-04-07 09:03:51.721150+00:00 │
│ Updated: 2026-04-07 09:03:51.721150+00:00 │
╰───────────────────────────────────────────╯
Step 8: Inspect a Resource (with File Content)
The inspect command can show file content from within a resource:
$ python -m cleveragents resource inspect local/my-repo --file README.md
Actual Output:
╭──────────── Resource Inspect ─────────────╮
│ Resource ID: 01KNKJY4X9K7ZDNEK7M6TKJTDG │
│ Name: local/my-repo │
│ Type: git-checkout │
│ Classification: physical │
│ Description: My project repository │
│ Location: /app │
│ Properties: │
│ path: /app │
│ Created: 2026-04-07 09:03:51.721150+00:00 │
│ Updated: 2026-04-07 09:03:51.721150+00:00 │
╰───────────────────────────────────────────╯
File: README.md
# CleverAgents Core
...
What's Happening:
The inspect command resolves the file path relative to the resource's
location, with path traversal protection. It reads and displays the file
content inline.
Step 9: Get JSON Output for Scripting
All resource commands support --format json for machine-readable output:
$ python -m cleveragents resource list --format json
Actual Output:
{
"command": "",
"status": "ok",
"exit_code": 0,
"data": [
{
"resource_id": "01KNKJY4X9K7ZDNEK7M6TKJTDG",
"name": "local/my-repo",
"type": "git-checkout",
"classification": "physical",
"description": "My project repository",
"location": "/app",
"properties": {
"path": "/app"
},
"lifecycle_state": null,
"created_at": "2026-04-07T09:03:51.721150+00:00",
"updated_at": "2026-04-07T09:03:51.721150+00:00"
}
]
}
What's Happening: The JSON output wraps the data in a structured envelope with status, exit code, and timing information — ideal for scripting and CI pipelines.
Part 2: Skill Management
Skills are reusable, namespaced collections of tools defined in YAML config files. They can bundle built-in tools, MCP server integrations, inline custom tools, and even include other skills.
Step 1: Register a Simple Skill
The simplest skill bundles built-in tools. Create a YAML file:
# single-tool.yaml
name: local/file-reader
description: "Basic file reading operations"
tools:
- name: builtin/read_file
- name: builtin/list_directory
- name: builtin/search_files
Register it:
$ python -m cleveragents skill add --config examples/skills/single-tool.yaml
Actual Output:
╭────────────── Skill Registered ───────────────╮
│ Name: local/file-reader │
│ Description: Basic file reading operations │
│ Config: examples/skills/single-tool.yaml │
│ Created: 2026-04-07 09:04 │
╰───────────────────────────────────────────────╯
╭─ Tool Sources ──╮
│ Source ┃ Count │
│ ━━━━━━━━╇━━━━━━ │
│ builtin │ 3 │
│ Total │ 3 │
╰─────────────────╯
✓ OK Skill registered with 3 tools
Step 2: Register a Skill with Inline Custom Tools
Inline tools are Python functions defined directly in the YAML:
# inline-tool.yaml
name: local/text-processing
description: "Simple text transformation utilities"
inline_tools:
- name: word_count
description: "Count words in text"
source: custom
code: |
def run(input_data):
text = input_data.get("text", "")
return {"count": len(text.split())}
input_schema:
type: object
properties:
text:
type: string
required: ["text"]
writes: false
- name: to_uppercase
description: "Convert text to uppercase"
source: custom
code: |
def run(input_data):
return {"result": input_data.get("text", "").upper()}
input_schema:
type: object
properties:
text:
type: string
required: ["text"]
writes: false
$ python -m cleveragents skill add --config examples/skills/inline-tool.yaml
Actual Output:
╭──────────────── Skill Registered ─────────────────╮
│ Name: local/text-processing │
│ Description: Simple text transformation utilities │
│ Config: examples/skills/inline-tool.yaml │
│ Created: 2026-04-07 09:04 │
╰───────────────────────────────────────────────────╯
╭─ Tool Sources ─╮
│ Source ┃ Count │
│ ━━━━━━━╇━━━━━━ │
│ custom │ 2 │
│ Total │ 2 │
╰────────────────╯
✓ OK Skill registered with 2 tools
Step 3: Register a Composed Skill (Includes + MCP)
Composed skills can include other skills and add MCP server integrations:
# composed.yaml
name: local/git-github
description: "Git operations and GitHub integration"
tools:
- name: builtin/git_status
- name: builtin/git_diff
- name: builtin/git_log
- name: builtin/git_blame
includes:
- name: local/file-reader # Inherits all tools from 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
- create_pull_request
- list_repos
- get_file_contents
$ python -m cleveragents skill add --config examples/skills/composed.yaml
Actual Output:
╭───────────────── Skill Registered ─────────────────╮
│ Name: local/git-github │
│ Description: Git operations and GitHub integration │
│ Config: examples/skills/composed.yaml │
│ Created: 2026-04-07 09:04 │
╰────────────────────────────────────────────────────╯
╭─────────── Includes ───────────╮
│ local/file-reader (registered) │
╰────────────────────────────────╯
╭─ Tool Sources ──╮
│ Source ┃ Count │
│ ━━━━━━━━╇━━━━━━ │
│ builtin │ 4 │
│ mcp │ 4 │
│ Total │ 8 │
╰─────────────────╯
╭──────── MCP Servers ────────╮
│ github: validated (4 tools) │
╰─────────────────────────────╯
✓ OK Skill registered with 8 tools
What's Happening:
The composed skill inherits all 3 tools from local/file-reader plus adds
4 git built-ins and 4 filtered MCP tools from the GitHub server — 11 total
when resolved (including inherited tools).
Step 4: List All Skills
$ python -m cleveragents skill list
Actual Output:
Skills (4 total)
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Name ┃ Description ┃ Tools ┃ Includes ┃ Sources ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ local/file-reader │ Basic file reading │ 3 │ 0 │ builtin │
│ │ operations │ │ │ │
│ local/git-github │ Git operations and │ 8 │ 1 │ builtin, mcp │
│ │ GitHub integration │ │ │ │
│ local/linear-track… │ Linear issue │ 0 │ 0 │ mcp │
│ │ tracking integration │ │ │ │
│ │ via MCP │ │ │ │
│ local/text-process… │ Simple text │ 2 │ 0 │ custom │
│ │ transformation │ │ │ │
│ │ utilities │ │ │ │
└─────────────────────┴──────────────────────┴───────┴──────────┴──────────────┘
╭──── Summary ────╮
│ Total: 4 │
│ Local: 4 │
│ Server: 0 │
│ Total Tools: 13 │
╰─────────────────╯
✓ OK 4 skills listed
Step 5: Filter Skills by Source Type
$ python -m cleveragents skill list --source mcp
Actual Output:
Skills (2 total)
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Name ┃ Description ┃ Tools ┃ Includes ┃ Sources ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ local/git-github │ Git operations and │ 8 │ 1 │ builtin, mcp │
│ │ GitHub integration │ │ │ │
│ local/linear-tracker │ Linear issue │ 0 │ 0 │ mcp │
│ │ tracking │ │ │ │
│ │ integration via MCP │ │ │ │
└──────────────────────┴─────────────────────┴───────┴──────────┴──────────────┘
Step 6: Show Full Skill Details
$ python -m cleveragents skill show local/git-github
Actual Output:
╭────────────────── Skill Details ───────────────────╮
│ Name: local/git-github │
│ Description: Git operations and GitHub integration │
│ Config: (unknown) │
│ Created: 2026-04-07 09:05 │
│ Updated: 2026-04-07 09:05 │
╰────────────────────────────────────────────────────╯
╭──────────── Includes (1) ─────────────╮
│ local/file-reader → 3 tools (builtin) │
╰───────────────────────────────────────╯
Direct Tools (8)
┏━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┓
┃ Name ┃ Source ┃ Writes ┃ Checkpoint ┃
┡━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━┩
│ builtin/git_status │ builtin │ — │ — │
│ builtin/git_diff │ builtin │ — │ — │
│ builtin/git_log │ builtin │ — │ — │
│ builtin/git_blame │ builtin │ — │ — │
│ create_issue │ mcp:github │ — │ — │
│ create_pull_request │ mcp:github │ — │ — │
│ list_repos │ mcp:github │ — │ — │
│ get_file_contents │ mcp:github │ — │ — │
└─────────────────────┴────────────┴────────┴────────────┘
╭───────── MCP Servers (1) ─────────╮
│ github: stdio, 4 tools, connected │
╰───────────────────────────────────╯
╭── Capability Summary ───╮
│ Total Tools: 11 │
│ Read-Only: 0 │
│ Writes: 0 │
│ Checkpointable: 0 │
│ Has Side Effects: False │
╰─────────────────────────╯
✓ OK Skill loaded
Step 7: View the Flattened Tool List
The tools command shows the complete resolved tool list including inherited tools:
$ python -m cleveragents skill tools local/git-github
Actual Output:
Tools for local/git-github
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┓
┃ Tool ┃ Source ┃ From Skill ┃ Read-Only ┃ Writes ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━┩
│ builtin/read_file │ builtin │ local/file-read │ — │ — │
│ builtin/list_directory │ builtin │ local/file-read │ — │ — │
│ builtin/search_files │ builtin │ local/file-read │ — │ — │
│ builtin/git_status │ builtin │ (direct) │ — │ — │
│ builtin/git_diff │ builtin │ (direct) │ — │ — │
│ builtin/git_log │ builtin │ (direct) │ — │ — │
│ builtin/git_blame │ builtin │ (direct) │ — │ — │
│ mcp:github/create_iss… │ mcp:github │ (direct) │ — │ — │
│ mcp:github/create_pul… │ mcp:github │ (direct) │ — │ — │
│ mcp:github/list_repos │ mcp:github │ (direct) │ — │ — │
│ mcp:github/get_file_c… │ mcp:github │ (direct) │ — │ — │
└────────────────────────┴────────────┴─────────────────┴───────────┴────────┘
╭───── Summary ─────╮
│ Total: 11 │
│ From Includes: 3 │
│ Direct: 8 │
│ Read-Only: 0 │
│ Writes: 0 │
│ Checkpointable: 0 │
╰───────────────────╯
✓ OK 11 tools listed
What's Happening:
The flattened tool list shows all 11 tools: 3 inherited from local/file-reader
(shown with their source skill) plus 8 direct tools. This is the exact tool set
an agent using this skill will have access to.
Step 8: Refresh Skills
After updating a skill's YAML config, refresh it to recompute the tool set:
$ python -m cleveragents skill refresh local/file-reader
Actual Output:
╭──── Skill Refreshed ────╮
│ Name: local/file-reader │
│ Total Tools: 3 │
│ Includes: 0 │
│ MCP Servers: 0 (n/a) │
│ Agent Skills: 0 │
│ Read-Only: 0 │
│ Writes: 0 │
│ Checkpointable: 0 │
╰─────────────────────────╯
✓ OK Skill refreshed with 3 tools
Or refresh all skills at once:
$ python -m cleveragents skill refresh --all
Actual Output:
Skills Refreshed (4)
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━┳━━━━━━━━┓
┃ Name ┃ Tools ┃ Includes ┃ MCP ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━╇━━━━━━━━┩
│ local/file-reader │ 3 │ 0 │ — │ ✓ │
│ local/git-github │ 11 │ 1 │ 1 │ ✓ │
│ local/linear-tracker │ 0 │ 0 │ 2 │ ✓ │
│ local/text-processing │ 2 │ 0 │ — │ ✓ │
└───────────────────────┴─────────┴──────────┴─────┴────────┘
✓ OK 4 skills refreshed
Part 3: LSP Server Management
CleverAgents also manages Language Server Protocol (LSP) servers as resources:
$ python -m cleveragents lsp list
Actual Output:
No LSP servers found.
Register one with 'agents lsp add --config <file>'
To register an LSP server, create a YAML config:
name: local/pyright
command: pyright-langserver
args: ["--stdio"]
languages: ["python"]
capabilities: ["diagnostics", "completions", "hover"]
Then register it:
$ python -m cleveragents lsp add --config pyright.yaml
The LSP resource type supports these parameters:
$ python -m cleveragents resource type show lsp-server
Actual Output:
╭─────────────────────────────── Resource Type ────────────────────────────────╮
│ Name: lsp-server │
│ Description: LSP server definition and running process. │
│ Kind: physical │
│ Sandbox Strategy: none │
│ Built-in: yes │
│ User-addable: yes │
│ CLI Arguments: │
│ --server-name (string, required) │
│ Unique server name │
│ --command (string, required) │
│ Path to server executable or command │
│ --language-ids (string, required) │
│ Comma-separated language identifiers (e.g. python,typescript) │
│ --transport (string, optional) │
│ Transport: stdio | tcp | pipe (default: stdio) │
│ Parent Types: container-instance, container-exec-env │
│ Child Types: lsp-workspace │
╰──────────────────────────────────────────────────────────────────────────────╯
Key Takeaways
- 101 built-in resource types cover git, filesystem, containers, cloud (AWS/GCP/Azure), databases, and LSP servers — no custom types needed for common use cases
- Namespaced names (
local/my-repo) keep user resources organized and prevent collisions with server-managed resources - Skills compose hierarchically — a skill can include other skills, inheriting their full tool sets
- Multiple output formats (
--format json,--format yaml,--format table) make all commands scriptable - Regex filtering on
resource type listlets you quickly find the right type from 100+ options - Capability summaries on skills show read-only vs write tool counts, helping you reason about agent safety
Try It Yourself
Now that you've seen the resource and skill management workflow, try these:
- Register an
fs-directoryresource pointing to a data directory - Create a skill that combines
builtin/read_filewith a custom inline tool - Use
--format jsonoutput withjqto extract specific fields:python -m cleveragents resource list --format json | jq '.data[].name' - Register an MCP-backed skill using a local MCP server
- Use
skill tools --format jsonto get a machine-readable tool inventory
Related Examples
- CleverAgents CLI Basics — version, info, and diagnostics
- Output Format Flags — using
--formatacross all commands - Config and Automation Profiles — configuring agent behavior
This example was automatically generated and verified by the CleverAgents UAT system. Feature area: Resource and skill management | Test cycle: 1 | Generated: 2026-04-07
Automated by CleverAgents Bot Supervisor: UAT Testing | Agent: uat-tester