CLI Reference

The wagents CLI manages AI agent assets in this repository — creating skills, agents, and MCP servers from templates, validating frontmatter, generating documentation, and packaging skills for distribution.

Installation

1. Clone the repository:

   git clone https://github.com/wyattowalsh/agents.git
   cd agents

2. Install with uv:

   uv sync

3. Verify installation:

   uv run wagents --version

Running commands

All wagents commands should be run with uv run wagents from the repository root. The examples below omit the uv run prefix for brevity.

Commands

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 mcp/ directory 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 validate — Check All Assets

Validate frontmatter and structure for every skill, agent, and MCP server in the repository:

wagents validate

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

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

# List available skills without installing
wagents install --list

# Copy files instead of symlinking
wagents install --copy

# Skip confirmation prompts
wagents install -y

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

---

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 ~/.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.

---

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

---

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
• 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/

  • …

Built With

uv Fast Python package manager.

Typer CLI framework for Python.

Starlight Documentation framework for this site.

ruff Fast Python linter and formatter.