CLI Reference

wagents is the repo control plane for skills, agents, MCP servers, and generated docs. Use it to scaffold new assets, validate the repo, publish docs, and package skills for release.

Harness MatrixShows supported agents consuming one portable skill bundle.

Boot Sequence

1. Sync the repo environment:

   uv sync

2. Sanity-check your toolchain:

   uv run wagents doctor

3. Validate the repo before making changes:

   uv run wagents validate

4. Start the docs site when you need to inspect generated output:

   uv run wagents docs dev

Running commands

Examples below omit the uv run prefix for brevity. In practice, run uv run wagents ... from the repository root.

Command Map

Command	Description
wagents new <asset>	Scaffold a new skill, agent, or MCP server from repo templates
wagents validate	Check frontmatter, naming, hooks, and related-skill integrity
wagents doctor	Sanity-check Python, uv, Node tooling, docs deps, and Playwright
wagents readme	Regenerate README.md or fail if it is stale
wagents openspec <subcommand>	Inspect, validate, and materialize OpenSpec workflows for downstream AI tools
wagents install	Install repo skills into supported agent platforms
wagents update	Refresh installed skills from their recorded sources
wagents skills <subcommand>	Inventory, sync, search, read, and diagnose local skills on demand
wagents package <name>	Build portable ZIP packages for sharing or release
wagents docs <subcommand>	Generate, serve, build, preview, or clean the docs site
wagents hooks <subcommand>	List and validate lifecycle hooks
wagents eval <subcommand>	List, validate, and check eval coverage

Command Reference

wagents new — Create Assets

Scaffold new skills, agents, or MCP servers from reference templates. Each template includes commented examples for all optional fields.

skill

Create a new skill with YAML frontmatter and markdown body:

wagents new skill my-skill

This creates skills/my-skill/SKILL.md with a complete template including all optional frontmatter fields as comments, and scaffolds a documentation page.

# Skip the docs page scaffold
wagents new skill my-skill --no-docs

Output structure:

skills/my-skill/
  SKILL.md          # Frontmatter + instructions

agent

Create a new agent configuration:

wagents new agent my-agent

This creates agents/my-agent.md with frontmatter for tools, permissions, model selection, and a system prompt body.

# Skip the docs page scaffold
wagents new agent my-agent --no-docs

mcp

Create a new MCP server with FastMCP v3:

wagents new mcp my-server

This creates a complete MCP server directory:

mcp/my-server/
  server.py         # FastMCP entry point with example tool
  pyproject.toml    # Package config with fastmcp>=2 dependency
  fastmcp.json      # FastMCP configuration

The command also adds the exact mcp/<name> entry to the uv workspace in pyproject.toml if not already present.

# Skip the docs page scaffold
wagents new mcp my-server --no-docs

Naming rules

All asset names must be kebab-case (^[a-z0-9][a-z0-9-]*$) and at most 64 characters. The name must match the directory name (for skills and MCP servers) or filename (for agents).

---

wagents openspec — Spec Workflow Control

Wrap OpenSpec CLI commands with repo defaults, downstream tool mappings, and OPENSPEC_TELEMETRY=0 for automation. Use these wrappers when AI agents need JSON status or instructions.

wagents openspec doctor
wagents openspec init --apply
wagents openspec status --change add-feature --format json
wagents openspec instructions design --change add-feature --format json
wagents openspec validate

Subcommands:

Command	Purpose
doctor	Check Node, npx, OpenSpec project files, generated artifacts, and tool mapping
init	Print or run openspec init for repo-supported downstream tools
update	Print or run openspec update after CLI/profile changes
validate	Run openspec validate --all --strict --json
status	Return artifact state for one change as JSON-compatible output
instructions	Return artifact or apply instructions as JSON-compatible output
schemas	List available OpenSpec schemas

Generated OpenSpec artifacts

OpenSpec-generated .claude, .cursor, .opencode, .github, .agent, .crush, .codex, and .gemini artifacts are local/generated unless a specific file is promoted to repo-owned source.

---

wagents validate — Check All Assets

Validate frontmatter and structure for every skill, agent, and MCP server in the repository. Also validates hook event names and RELATED_SKILLS references.

wagents validate

# Output as JSON or JSONL
wagents validate --format json

What it checks:

Asset type	Validations
Skills	Required name and description fields, kebab-case naming, name matches directory, description within 1024 chars, body is non-empty
Agents	Required name and description fields, kebab-case naming, name matches filename
MCP servers	Directory is kebab-case, server.py exists and references FastMCP, pyproject.toml includes fastmcp dependency, fastmcp.json exists
Hooks	Hook event names are known lifecycle events across skills, agents, and settings
Related skills	Every key and value in RELATED_SKILLS maps to an existing skill directory

The command exits with code 1 if any validation fails, printing each error to stderr.

CI integration

Run wagents validate in your CI pipeline to catch frontmatter issues before merge. It is included in the repository’s pre-commit and CI checks.

---

wagents doctor — Environment Health Check

Diagnose your local environment and toolchain. Checks for required tools, correct Python version, docs dependency status, and Playwright availability.

wagents doctor

# Output as JSON for scripting
wagents doctor --format json

What it checks:

Check	Status on failure
Python version satisfies requires-python	fail
uv on PATH	fail
node, npx, pnpm on PATH	warn
docs/node_modules present and fresh	warn
Playwright Python package installed	warn
Playwright browser cache exists	warn

Exits with code 1 if any check has fail status. Warnings are informational and do not affect the exit code.

First-time setup

Run wagents doctor after cloning to verify your environment before working with skills or docs.

---

wagents readme — Generate README

Regenerate README.md from the current repository contents, or check if the existing README is up to date:

# Fully regenerate README.md
wagents readme

# Check if README is stale (exits 1 if out of date)
wagents readme --check

The generated README includes tables for all skills, agents, and MCP servers, plus a development commands reference.

---

wagents install — Install Skills

Install skills into agent platforms via npx skills:

# Install all skills to all supported agents globally
wagents install

# Install specific skill(s)
wagents install my-skill

# Install to a specific agent
wagents install -a claude-code

# Project-local install instead of global
wagents install --local

# List available skills without installing
wagents install --list

# Copy files instead of symlinking
wagents install --copy

# Skip confirmation prompts
wagents install -y

For third-party skill sources or curated subsets, use npx skills add directly:

npx skills add <source> --skill <name> -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent opencode

Option	Default	Description
<skills>	all	Positional skill name(s) to install
-a, --agent	all	Target agent(s), repeatable
-g, --global	true	Install globally (default)
--local	false	Install into current project only
--list	false	List available skills without installing
--copy	false	Copy files instead of symlinking
-y, --yes	false	Skip confirmation prompts

Supported agents: antigravity, claude-code, codex, crush, cursor, gemini-cli, github-copilot, opencode

---

wagents update — Refresh Installed Skills

Refresh installed skills from the sources recorded by the skills CLI. Use this after this repository changes so downstream agent installs pick up the latest committed skill files.

wagents update

# Equivalent lower-level command
npx skills update

---

wagents skills sync — Additive Cross-Harness Sync

Build a normalized installed-skill inventory from npx skills ls -g -a <agent> --json, then preview or apply additive installs for the desired sync set.

# Default mode is dry-run across all supported harnesses
wagents skills sync

# Target one harness
wagents skills sync --agent github-copilot

# Include verified one-off installed external skills
wagents skills sync --include-installed

# Execute the verified install commands
wagents skills sync --apply

Option	Default	Description
-a, --agent	all	Restrict sync to one or more harnesses
--all-agents	false	Explicitly target all supported harnesses
--dry-run	true	Preview missing, already-present, unresolved, skipped rows, and exact install commands
--apply	false	Execute only the verified additive install commands
--include-installed	false	Include verified one-off installed external skills outside the curated desired set

Desired sync set

By default, sync targets repo-owned custom skills plus verified curated external skills. It never removes user-installed skills.

GitHub Copilot caveat

GitHub Copilot remains part of config and instruction sync, but the skills inventory reports only what the Skills CLI returns. A legitimate 0 installed-skills result stays 0.

---

wagents skills — On-Demand Skill Index

Inspect repository, installed, curated, and plugin skills without loading every skill description into startup context. Use this when local skill inventory exceeds an agent’s context budget or when you need additive sync diagnostics.

sync

Preview additive cross-harness installs from the normalized inventory:

wagents skills sync --dry-run

# Narrow to one harness and include verified one-off installs
wagents skills sync --agent codex --include-installed

search

Search for matching skills with deterministic lexical ranking:

wagents skills search "fix GitHub Actions workflow"

# Restrict to repo skills and emit JSON
wagents skills search "release notes" --source repo --format json

context

Build a compact context packet from the top matching skill bodies:

wagents skills context "debug browser rendering" --limit 3

read

Read one known skill by exact name or path:

wagents skills read skill-router
wagents skills read /path/to/SKILL.md

doctor

Inspect skill roots, counts, and warning totals:

wagents skills doctor

Source	Roots
repo	skills/
project	.agents/skills/ in the current project path
codex	~/.codex/skills/
global	~/.agents/skills/ plus supported agent skill stores
plugin	~/.codex/plugins/cache/**/skills/

Each result includes name, path, source, trust_tier, score, matched fields, and warnings.

---

wagents package — Package Skills

Package skills into portable ZIP files for distribution:

# Package a single skill
wagents package my-skill

# Package all skills
wagents package --all

# Check portability without creating ZIPs
wagents package --dry-run

# Specify output directory
wagents package my-skill --output dist/

# Output as JSON instead of table
wagents package my-skill --format json

Packaged ZIPs are self-contained and can be distributed independently or attached to GitHub releases.

Automated releases

The release-skills.yml CI workflow automatically packages and releases all skills when a version tag (v*.*.*) is pushed.

---

wagents docs — Documentation Site

Manage the Starlight-powered documentation site at agents.w4w.dev.

init

One-time setup to install documentation dependencies:

wagents docs init

This runs pnpm install in the docs/ directory.

generate

Generate MDX content pages, sidebar, and index pages from repository assets:

wagents docs generate

Options:

# Include installed skills from local agent skill directories (~/.config/opencode/skills/, ~/.agents/skills/, ~/.claude/skills/)
wagents docs generate --include-installed

# Include skills with TODO descriptions
wagents docs generate --include-drafts

By default, generation is deterministic and repository-only. The generator creates individual pages for each skill, agent, and MCP server, plus category index pages and the sidebar navigation.

dev

Generate content and start the development server with hot reload:

wagents docs dev

build

Generate content and produce a static build:

wagents docs build

Output goes to docs/dist/.

preview

Generate, build, and start a preview server for the production build:

wagents docs preview

clean

Remove generated content pages while preserving hand-maintained files:

wagents docs clean

Files containing HAND-MAINTAINED in their content are preserved during clean operations.

Typical docs workflow

For day-to-day development, wagents docs dev is the most common command — it regenerates all content and launches a hot-reloading dev server in one step.

---

wagents hooks — Lifecycle Hooks

Inspect and validate lifecycle hooks defined in .claude/settings.json, skill frontmatter, agent frontmatter, and the portable config/hook-registry.json.

list

List all hooks across skills, agents, settings, and the portable hook registry:

wagents hooks list

# Output as JSON
wagents hooks list --format json

Shows source, event, matcher, harness support, handler type, and command/prompt for each hook.

validate

Validate hook definitions for correct structure and known event names:

wagents hooks validate

Checks that every hook event is a known lifecycle event (PreToolUse, PostToolUse, etc.), handler types are valid (command, prompt, agent), registry harnesses are supported, and required fields are present.

---

wagents eval — Skill Evals

Manage and validate eval files stored in skills/<name>/evals/*.json. Evals define test queries and expected behaviors for skills.

list

List all eval files grouped by skill:

wagents eval list

# Output as JSON
wagents eval list --format json

validate

Validate eval JSON files for required fields and referential integrity:

wagents eval validate

Legacy scenario files must contain skills, query, and expected_behavior. Canonical manifests may use evals/evals.json with skill_name plus an evals array of cases containing prompt and expected_output, with optional files and assertions.

coverage

Show which skills have evals and how many:

wagents eval coverage

Useful for identifying skills that lack test coverage.

---

Structured Output All validation commands

Most inspection and validation commands accept --format to control output:

Format	Description
text	Human-readable table output (default)
json	Single JSON object with full results
jsonl	One JSON object per line — ideal for piping to jq or log aggregators

Commands supporting --format: validate, doctor, hooks list, hooks validate, eval list, eval validate, eval coverage, skills index, skills search, skills read, skills context, skills doctor.

---

Common Workflows

Adding a new skill end-to-end

1. Scaffold the skill:

   wagents new skill my-skill

2. Edit skills/my-skill/SKILL.md with your instructions.

3. Validate the frontmatter:

   wagents validate

4. Preview the docs page:

   wagents docs dev

5. Package for distribution:

   wagents package my-skill

Updating documentation after changes

1. Regenerate all docs:

   wagents docs generate

2. Rebuild the README:

   wagents readme

3. Run validation:

   wagents validate

Checking environment health

1. Run the doctor check:

   wagents doctor

2. Fix any FAIL items shown in the output.

3. Run validation and hook checks:

   wagents validate && wagents hooks validate

---

Repository Structure

• Directoryskills/

  • Directory<name>/

    • SKILL.md
    • Directoryreferences/ (optional)

      • …
    • Directoryscripts/ (optional)

      • …
    • Directoryevals/ (optional)

      • …
• Directoryagents/

  • <name>.md
• Directorymcp/

  • Directory<name>/

    • server.py
    • pyproject.toml
    • fastmcp.json
  • Directoryservers/ (ignored local third-party installs)

    • …
• Directorydocs/ (this site)

  • Directorysrc/

    • Directorycontent/

      • Directorydocs/ (generated MDX pages)

        • …
    • generated-sidebar.mjs
• Directorywagents/

  • __init__.py
  • cli.py
  • parsing.py
  • catalog.py
  • rendering.py
  • docs.py
• Directorytests/

  • …

Related Pages

Skills Catalog Browse all available skills.

Agents Directory Browse agent configurations in the repository.

MCP Servers Browse MCP server integrations.

Built With

uv Fast Python package manager.

Typer CLI framework for Python.

ty Fast Python type checker.

Starlight Documentation framework for this site.

ruff Fast Python linter and formatter.