From 2aaeed67bcbbf3e04deeab5b3e50f17dccb3acbf Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Tue, 7 Apr 2026 09:11:10 +0000 Subject: [PATCH] docs: add showcase example for resource and skill management ISSUES CLOSED: #4470 --- .../resource-and-skill-management.md | 109 +++++++----------- 1 file changed, 40 insertions(+), 69 deletions(-) diff --git a/docs/showcase/cli-tools/resource-and-skill-management.md b/docs/showcase/cli-tools/resource-and-skill-management.md index a29e0ceab..b984cdd31 100644 --- a/docs/showcase/cli-tools/resource-and-skill-management.md +++ b/docs/showcase/cli-tools/resource-and-skill-management.md @@ -13,9 +13,13 @@ captured from a live installation. - CleverAgents installed (`pip install cleveragents` or from source with `uv sync`) - Python 3.12 or higher +> **Note:** All examples use the canonical `agents` CLI described in the +> specification. You can also run the toolkit with `python -m cleveragents`, +> but `agents` keeps command names consistent across the docs. + ## What You'll Learn -- How to explore the 100+ built-in resource types +- How to explore the 101 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 @@ -32,7 +36,7 @@ CleverAgents ships with 100+ built-in resource types covering git, filesystem, containers, cloud providers (AWS, GCP, Azure), databases, and LSP servers. ```bash -$ python -m cleveragents resource type list +$ agents resource type list ``` **Actual Output (truncated):** @@ -64,7 +68,7 @@ whether users can add instances of it. You can filter the type list with a regex pattern: ```bash -$ python -m cleveragents resource type list "git.*" +$ agents resource type list "git.*" ``` **Actual Output:** @@ -96,7 +100,7 @@ Get full details about a resource type including its CLI arguments and parent/child relationships: ```bash -$ python -m cleveragents resource type show git-checkout +$ agents resource type show git-checkout ``` **Actual Output:** @@ -132,7 +136,7 @@ It can have child resources of types `git`, `fs-directory`, `fs-file`, etc. Add a git checkout resource pointing to a local repository: ```bash -$ python -m cleveragents resource add git-checkout local/my-repo \ +$ agents resource add git-checkout local/my-repo \ --path /path/to/your/repo \ --description "My project repository" ``` @@ -150,7 +154,7 @@ opposed to server-managed resources). ### Step 5: List Registered Resources ```bash -$ python -m cleveragents resource list +$ agents resource list ``` **Actual Output:** @@ -166,7 +170,7 @@ $ python -m cleveragents resource list ### Step 6: Filter Resources by Type ```bash -$ python -m cleveragents resource list --type git-checkout +$ agents resource list --type git-checkout ``` **Actual Output:** @@ -182,7 +186,7 @@ $ python -m cleveragents resource list --type git-checkout ### Step 7: Show Resource Details ```bash -$ python -m cleveragents resource show local/my-repo +$ agents resource show local/my-repo ``` **Actual Output:** @@ -206,7 +210,7 @@ $ python -m cleveragents resource show local/my-repo The `inspect` command can show file content from within a resource: ```bash -$ python -m cleveragents resource inspect local/my-repo --file README.md +$ agents resource inspect local/my-repo --file README.md ``` **Actual Output:** @@ -239,7 +243,7 @@ content inline. All resource commands support `--format json` for machine-readable output: ```bash -$ python -m cleveragents resource list --format json +$ agents resource list --format json ``` **Actual Output:** @@ -297,7 +301,7 @@ tools: Register it: ```bash -$ python -m cleveragents skill add --config examples/skills/single-tool.yaml +$ agents skill add --config examples/skills/single-tool.yaml ``` **Actual Output:** @@ -358,7 +362,7 @@ inline_tools: ``` ```bash -$ python -m cleveragents skill add --config examples/skills/inline-tool.yaml +$ agents skill add --config examples/skills/inline-tool.yaml ``` **Actual Output:** @@ -414,7 +418,7 @@ mcp_servers: ``` ```bash -$ python -m cleveragents skill add --config examples/skills/composed.yaml +$ agents skill add --config examples/skills/composed.yaml ``` **Actual Output:** @@ -449,7 +453,7 @@ when resolved (including inherited tools). ### Step 4: List All Skills ```bash -$ python -m cleveragents skill list +$ agents skill list ``` **Actual Output:** @@ -478,10 +482,14 @@ $ python -m cleveragents skill list ✓ OK 4 skills listed ``` +> **Why the extra skill?** The demo environment already had the +> `local/linear-tracker` MCP skill registered. If you're following along on a +> clean installation you'll only see the three skills created in Steps 1–3. + ### Step 5: Filter Skills by Source Type ```bash -$ python -m cleveragents skill list --source mcp +$ agents skill list --source mcp ``` **Actual Output:** @@ -501,7 +509,7 @@ $ python -m cleveragents skill list --source mcp ### Step 6: Show Full Skill Details ```bash -$ python -m cleveragents skill show local/git-github +$ agents skill show local/git-github ``` **Actual Output:** @@ -547,7 +555,7 @@ $ python -m cleveragents skill show local/git-github The `tools` command shows the complete resolved tool list including inherited tools: ```bash -$ python -m cleveragents skill tools local/git-github +$ agents skill tools local/git-github ``` **Actual Output:** @@ -584,57 +592,12 @@ 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: - -```bash -$ 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: - -```bash -$ 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: ```bash -$ python -m cleveragents lsp list +$ agents lsp list ``` **Actual Output:** @@ -650,19 +613,27 @@ name: local/pyright command: pyright-langserver args: ["--stdio"] languages: ["python"] +transport: stdio capabilities: ["diagnostics", "completions", "hover"] ``` Then register it: ```bash -$ python -m cleveragents lsp add --config pyright.yaml +$ agents lsp add --config pyright.yaml ``` +> **Spec alignment:** The YAML fields map 1:1 to the CLI arguments exposed by +> `agents resource type show lsp-server`. `name` supplies `--server-name`, +> `command` plus optional `args` become `--command`/`--args`, `languages` +> populate `--language-ids`, and `transport` maps to `--transport`. Using the +> config file keeps multi-value fields readable while staying within the +> documented schema. + The LSP resource type supports these parameters: ```bash -$ python -m cleveragents resource type show lsp-server +$ agents resource type show lsp-server ``` **Actual Output:** @@ -714,16 +685,16 @@ Now that you've seen the resource and skill management workflow, try these: - Create a skill that combines `builtin/read_file` with a custom inline tool - Use `--format json` output with `jq` to extract specific fields: ```bash - python -m cleveragents resource list --format json | jq '.data[].name' + agents resource list --format json | jq '.data[].name' ``` - Register an MCP-backed skill using a local MCP server - Use `skill tools --format json` to get a machine-readable tool inventory ## Related Examples -- [CleverAgents CLI Basics](./cleveragents-cli-basics.md) — version, info, and diagnostics -- [Output Format Flags](./output-format-flags.md) — using `--format` across all commands -- [Config and Automation Profiles](./config-and-automation-profiles.md) — configuring agent behavior +- [CLI Tools Overview](./README.md) — quick reference to all CLI-focused showcase docs +- [Showcase Example Template](../example-template.md) — guidelines for authoring new walkthroughs +- [Showcase Index](../index.md) — browse every published showcase example --- *This example was automatically generated and verified by the CleverAgents UAT system.*