docs: add showcase example for resource and skill management
ISSUES CLOSED: #4470
This commit is contained in:
@@ -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.*
|
||||
|
||||
Reference in New Issue
Block a user