cmdop-skill

Build and publish CMDOP skills — self-contained packages that extend the CMDOP agent with new capabilities.

Install


pip install cmdop-skill

Quick Start

Scaffold a new skill


cmdop-skill init

Interactive wizard: name (with PyPI availability check), description, author. Category, tags, and visibility are determined automatically by the server during publish.

Or write one from scratch


from cmdop_skill import Skill, Arg
 
skill = Skill()  # name, version, description from pyproject.toml
 
@skill.command
async def greet(name: str = Arg(help="Who to greet", required=True)) -> dict:
    """Say hello."""
    return {"message": f"Hello, {name}!"}
 
if __name__ == "__main__":
    skill.run()

Skill() auto-resolves name, version, description from the nearest pyproject.toml.

Framework Features

@skill.command — turn async/sync functions into CLI subcommands
Arg() — declarative arguments with help, required, default, choices, nargs, action
@skill.setup / @skill.teardown — lifecycle hooks (async)
TestClient — test harness (client.run() and client.run_cli())
pyproject.toml as single source of truth — no metadata duplication
Auto src/ path — src/ is added to sys.path automatically
JSON output — all commands return {"ok": true, ...} by default

CLI Commands

Command	Description
`init [path]`	Scaffold a new skill project (interactive wizard)
`install <path>`	Symlink skill into system skills directory
`uninstall <name>`	Remove skill from system skills directory
`run <path> <prompt>`	Run skill via CMDOP SDK
`test <path>`	Run pytest in skill directory
`bump [path]`	Bump version in pyproject.toml (semver)
`check-name <name>`	Check if package name is available on PyPI
`release [path]`	Bump + build + upload to PyPI + publish to CMDOP
`publish`	Publish skill to the CMDOP marketplace
`list`	List your published skills
`config set-key`	Save API key globally
`config show`	Show saved config (key masked)
`config reset`	Remove saved API key

init


cmdop-skill init                        # scaffold in current directory
cmdop-skill init ./skills               # scaffold in ./skills/

Also available programmatically:


from cmdop_skill.scaffold import ScaffoldConfig, scaffold_skill
from pathlib import Path
 
config = ScaffoldConfig(name="my-skill", description="Does things")
files = scaffold_skill(config, target_dir=Path("."))

config

API key is resolved in order: --api-key flag > CMDOP_API_KEY env > saved config > interactive prompt.


cmdop-skill config set-key              # interactive (masked input)
cmdop-skill config set-key cmdop_xxx    # direct
cmdop-skill config show
cmdop-skill config reset

install / uninstall


cmdop-skill install ./skills/my-skill
# Installed my-skill -> ~/Library/Application Support/cmdop/skills/my-skill (symlink)
 
cmdop-skill uninstall my-skill

bump


cmdop-skill bump                        # patch: 0.1.0 -> 0.1.1
cmdop-skill bump --minor                # minor: 0.1.1 -> 0.2.0
cmdop-skill bump --major                # major: 0.2.0 -> 1.0.0

check-name


cmdop-skill check-name my-cool-skill
# my-cool-skill is available on PyPI
 
cmdop-skill check-name requests
# requests is taken on PyPI

release

Full pipeline — bump, build, publish to CMDOP marketplace, upload to PyPI:


cmdop-skill release                     # bump patch + build + PyPI + CMDOP
cmdop-skill release -b minor            # bump minor
cmdop-skill release --no-bump           # current version
cmdop-skill release --test-pypi         # TestPyPI only (skips CMDOP)
cmdop-skill release --no-publish        # PyPI only (skips CMDOP)

Publish

Only the skill name is required to create a skill on the marketplace. Everything else is automatic:

Category — determined by the server from manifest keywords
Tags — extracted from pyproject.toml keywords
Description — from README / pyproject.toml
Visibility — public by default
Translations — generated server-side via LLM (17 languages)


cmdop-skill publish --path .            # publish to prod
cmdop-skill publish --json              # CI mode (no interactive prompts)

Skill Structure


my-skill/
├── pyproject.toml          # Package metadata, deps, build config
├── Makefile                # Dev shortcuts
├── README.md
├── .gitignore
├── skill/
│   ├── config.py           # SkillConfig manifest (required)
│   └── readme.md           # LLM system prompt
├── src/my_skill/
│   ├── __init__.py
│   └── _skill.py           # Skill commands
└── tests/
    ├── conftest.py
    └── test_my_skill.py

skill/config.py

Minimal — everything is auto-resolved from pyproject.toml:


from cmdop_skill import SkillConfig
 
config = SkillConfig()

Optional fields:


config = SkillConfig(
    changelog="Fixed timeout handling.",
    short_description="Brief summary (max 300 chars).",
)

Testing


from cmdop_skill import TestClient
from my_skill._skill import skill
 
client = TestClient(skill)
 
# Keyword invocation
result = await client.run("greet", name="World")
assert result["ok"] is True
 
# CLI-style invocation
result = await client.run_cli("greet", "--name", "World")
assert result["ok"] is True

Python API

Export	Description
`Skill`	Main class — registers commands, runs CLI
`Arg`	Argument descriptor with metadata
`SkillConfig`	Typed skill manifest (pydantic model)
`TestClient`	Test harness
`resolve_project_meta`	Resolve metadata from nearest `pyproject.toml`
`generate_manifest`	Generate `skill/config.py` content
`publish_skill`	Programmatic publish to marketplace
`json_output` / `wrap_result` / `format_error`	Output formatting helpers
`scaffold.ScaffoldConfig`	Pydantic model for scaffold parameters
`scaffold.scaffold_skill`	Generate a complete skill directory

Example Skills

The cmdop-skills-lab repository contains production-ready example skills:

Skill	Description
ssl-cert-checker	Check SSL certificate expiry dates for domains
cmdop-coder	Code analysis with tree-sitter AST parsing (40+ languages)
cmdop-sdkrouter	Unified AI services SDK (14 service groups)
llm-email	Send emails via macOS Mail.app with AppleScript
llm-html	LLM-optimized HTML cleaning and extraction
tg-notify	Rate-limited Telegram notifications with priority queue

Each skill follows the same structure: skill/config.py, skill/readme.md, src/<pkg>/, tests/, Makefile.


# Clone and explore
git clone https://github.com/commandoperator/cmdop-skills-lab
cd cmdop-skills-lab/libs/ssl-cert-checker
pip install -e '.[dev]'
make test