Feat/issue 126 cli examples

CHANGELOG.md

@@ -18,6 +18,7 @@ Contributors add user-facing entries under `[Unreleased]` in the same PR. Mainta
 ### Added
 
 - **CLI**: `skillware test` runs bundle tests via pytest — all roots, by skill ID, or by `--category`; supports `-v` and `--no-header`. Documented in [cli.md](docs/usage/cli.md), [TESTING.md](docs/TESTING.md), and contributor guides (#83).
+- **CLI**: `skillware list --examples` shows per-skill example script counts; `skillware examples [skill_id]` lists indexed runnable scripts from `examples/README.md` with GitHub source links; interactive menu option **examples** (#126). Ships `examples/README.md` in the wheel so pip installs can resolve the index.
 
 ## [0.3.7] - 2026-06-22
 

MANIFEST.in

@@ -1,3 +1,4 @@
 graft skills
+include examples/README.md
 global-exclude __pycache__
 global-exclude *.py[cod]

docs/usage/README.md

@@ -21,7 +21,7 @@ To list locally available skills or run bundle tests from the terminal, see the
 | OpenAI (ChatGPT) | `to_openai_tool()` | [openai.md](openai.md) | `OPENAI_API_KEY` |
 | DeepSeek | `to_deepseek_tool()` | [deepseek.md](deepseek.md) | `DEEPSEEK_API_KEY` |
 | Ollama (prompt mode) | `to_ollama_prompt()` | [ollama.md](ollama.md) | (local; no cloud key) |
-| CLI | `skillware list`, `skillware test` | [cli.md](cli.md) | pytest in `[dev]` for `test` |
+| CLI | `skillware list`, `skillware test`, `skillware examples` | [cli.md](cli.md) | pytest in `[dev]` for `test` |
 
 Skill-specific **Usage Examples** (sample prompts and execute payloads) live on each [skill catalog page](../skills/README.md).
 

docs/usage/cli.md

@@ -18,6 +18,7 @@ After installation, the `skillware` command is available directly:
     skillware
     skillware list
     skillware test
+    skillware examples
     skillware --version
 
 If `skillware` is not recognized, Python's `Scripts` directory may not be on
@@ -78,9 +79,9 @@ Available commands:
 | Input | Command | Status |
 | :--- | :--- | :--- |
 | `1` / `list` | List all locally installed skills | Available |
-| `2` / `paths` | Show and repair skill directory resolution paths | Coming soon |
 | `3` / `test` | Run bundle tests (`test_skill.py`) for one or all skills | Available |
-| `4` / `help` | Print rich-formatted help with commands, flags, and examples | Available |
+| `4` / `paths` | Show and repair skill directory resolution paths | Coming soon |
+| `5` / `help` | Print rich-formatted help with commands, flags, and examples | Available |
 
 ## Commands
 
@@ -104,18 +105,44 @@ Sample output:
 | `--category <name>` | Show only skills in the given category. Discovered at runtime, never hardcoded. |
 | `--issuer <handle>` | Show only skills by a given GitHub handle or issuer name. |
 | `--skills-root <path>` | Override the skills directory for this command only. |
+| `--examples` | Add an **EXAMPLES** column with the count of indexed scripts per skill (`-` when none). Works with `--category` and `--issuer`. |
 
 #### Examples
 
     # Filter by category
     skillware list --category compliance
 
+    # Show example script counts per skill
+    skillware list --examples
+    skillware list --examples --category dev_tools
+
     # Filter by issuer
     skillware list --issuer rosspeili
 
     # Use a custom skills directory
     skillware list --skills-root /path/to/my/skills
 
+### skillware examples
+
+List runnable scripts indexed in `examples/README.md` (source of truth — the CLI does not scan `examples/*.py` directly).
+
+    skillware examples
+    skillware examples compliance/tos_evaluator
+    skillware examples finance/wallet_screening
+
+#### Arguments
+
+| Input | Description |
+| :--- | :--- |
+| *(no args)* | All indexed scripts (script-first view) |
+| `<category>/<skill_name>` | Scripts linked to that skill ID only |
+
+Columns: Script, Skill ID(s), Provider, Required extra, and a **GITHUB** link to the script on `main` (for example `https://github.com/ARPAHLS/skillware/blob/main/examples/gemini_tos_evaluator.py`). Environment variables and longer notes stay in `examples/README.md`; a one-line pointer is printed below the table.
+
+Unknown skill IDs exit with a helpful message and non-zero status.
+
+In the interactive menu, choose **`2` / `examples`**, optionally enter a skill ID, then browse the same table with GitHub links.
+
 ### skillware test
 
 Run skill **bundle tests** (`test_skill.py`) via pytest. Uses the same skill roots as `skillware list` (`SKILLWARE_SKILL_PATH`, `--skills-root`, cwd `skills/`, bundled registry).

docs/vision.md

@@ -106,7 +106,7 @@ Honest snapshot for **v0** (current v0.3.x line):
 
 - **Registry**: Skills under `skills/` with docs in [docs/skills/](skills/README.md).
 - **Loader**: Dynamic import, dependency checks, and adapters for major LLM tool formats.
-- **CLI**: `skillware list`, `skillware test`, and an interactive menu, included with `pip install skillware`.
+- **CLI**: `skillware list`, `skillware test`, and an interactive menu, included with `pip install skillware`. Use `skillware list --examples` and `skillware examples` to browse the runnable script index from the terminal.
 - **Active work**: Wallet screening enhancements ([RFC #115](https://github.com/ARPAHLS/skillware/issues/115)), CLI polish, contributor docs, and good first issues across docs and framework.
 
 Browse [open good first issues](https://github.com/ARPAHLS/skillware/issues?q=is%3Aopen+label%3A%22good+first+issue%22) if you want a low-risk entry point.

examples/README.md

@@ -4,7 +4,9 @@
 
 Runnable examples in this directory show how to load Skillware skills, adapt
 them for a provider, execute local skill logic, and return tool results to an
-agent loop. Provider setup details live in the usage guides:
+agent loop. From the repository root, run `skillware examples` or
+`skillware list --examples` to browse the index in the terminal (see
+[CLI reference](../docs/usage/cli.md)). Provider setup details live in the usage guides:
 
 - [API keys for skills](../docs/usage/api_keys.md)
 - [Gemini](../docs/usage/gemini.md)