Skip to content

cli.md

Latest commit

 

History

History
181 lines (120 loc) · 5.96 KB

cli.md

File metadata and controls

181 lines (120 loc) · 5.96 KB

CLI Reference

Skillware ships a skillware command-line tool for discovering and inspecting skills installed locally. It mirrors the same path resolution order used by SkillLoader.load_skill(), so the skills listed are exactly the ones your agent can load.

Installation

Install Skillware — rich is included as a core dependency:

pip install skillware

Running the CLI

After installation, the skillware command is available directly:

skillware
skillware list
skillware test
skillware --version

If skillware is not recognized, Python's Scripts directory may not be on your PATH.

Unix — verify with:

which skillware

Windows — verify with:

where skillware

If the command is not found, use the module fallback (works on any OS as long as Python is installed):

python -m skillware
python -m skillware list
python -m skillware test finance/wallet_screening
python -m skillware list --category compliance
python -m skillware --help

Windows PATH fix — add both Python3x\ and Python3x\Scripts\ to your system PATH, or use the py launcher:

py -3 -m pip install skillware
py -3 -m skillware list

Version advisory

On CLI startup, Skillware checks the installed package version once per process. If you are on an unsupported release (below 0.2.6, for example 0.2.5), a single dim message is printed to stderr suggesting an upgrade to >= 0.3.1. Current and recent installs (0.2.6 and above) stay silent so normal use is not spammed.

Library use (import skillware, SkillLoader) never prints this message.

To disable the check in CI or automation:

export SKILLWARE_NO_VERSION_CHECK=1

See SECURITY.md for the full supported-version policy.

Interactive menu

Running skillware with no arguments launches an ASCII splash screen and an interactive numbered menu:

skillware

The splash displays the current version and links to the project site and repository. The menu accepts both number input (1) and command name (list). After each command completes, the menu re-prints automatically. Press q or Ctrl+C to exit.

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

Commands

skillware list

Print a table of all locally available skills.

skillware list

Sample output:

ID                           VERSION  CATEGORY    ISSUER      DESCRIPTION                                       REQUIREMENTS
compliance/pii_masker        0.1.0    compliance  rosspeili   Detects and redacts PII locally using Ollama.     requests
finance/wallet_screening     1.0.0    finance     rosspeili   Screens Ethereum wallets against OFAC sanctions.  requests
office/pdf_form_filler       0.1.0    office      rosspeili   Fills PDF forms from natural language.            pymupdf, anthropic

Flags

Flag Description
--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

# Filter by category
skillware list --category compliance

# Filter by issuer
skillware list --issuer rosspeili

# Use a custom skills directory
skillware list --skills-root /path/to/my/skills

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

Requires pytest (pip install -e ".[dev]" or pip install -e ".[dev,all]").

skillware test
skillware test finance/wallet_screening
skillware test --category compliance
skillware test --verbose
skillware test office/pdf_form_filler --no-header

Arguments and flags

Input Description
(no args) Run bundle tests under all resolved skill roots
<category>/<skill_name> Run one skill's test_skill.py
--category <name> Run all bundle tests in a category directory
--skills-root <path> Override the skills directory for this command
-v / --verbose Pass -v to pytest
--no-header Pass --no-header to pytest

Exit code matches pytest (non-zero on failures or missing test paths).

Path resolution

skillware list searches for skills in the same order as SkillLoader:

  1. Roots listed in SKILLWARE_SKILL_PATH (OS path separator between multiple entries)
  2. A skills/ directory under the current working directory and its parents
  3. Bundled skills installed with the skillware package

To point the CLI at a persistent custom root, set the environment variable:

export SKILLWARE_SKILL_PATH=/path/to/my/skills
skillware list

Only skills with both manifest.yaml and skill.py present are shown — the same condition SkillLoader requires to load a skill successfully.

Color theme

The CLI uses a pastel color palette consistent with the project's visual identity:

Element Color Hex
Table headers and borders Lavender #C7CEEA
Category column Peach #FFDAC1
Skill ID column Mint #B5EAD7
Splash screen Lavender #C7CEEA
Interactive menu Peach #FFDAC1

short_description field

Skill manifests can include a short_description field (max 80 chars) for a concise one-line summary shown in skillware list:

short_description: "Screens Ethereum wallets against OFAC sanctions and mixer lists."

If short_description is absent, the CLI falls back to the first sentence of description, truncated to 80 characters.