Skill CLI Template

A standardized template for building CLI tools that work seamlessly as Nexus/Cursor skills.

Philosophy

Every CLI tool that wraps a data source should follow the same patterns:

1. init — First-time setup (config, database)
2. sync — ETL from source (idempotent, incremental)
3. db query — Raw SQL access (no feature requests needed)
4. search — Semantic search (optional but powerful)
5. --json — Machine-readable output everywhere

This makes tools predictable for AI agents. An agent that knows one skill CLI can use them all.

AI-Friendly Design Principles

1. Predictable Commands

Every skill CLI has the same core commands. Agents don't need to learn new patterns.

2. JSON Output

All commands support --json for structured output. Agents can parse and act on results.

3. Raw SQL Access

db query <sql> lets agents run arbitrary queries without waiting for new features.

4. Clear Errors

Error messages include:

• What went wrong
• Why it might have happened
• How to fix it

5. Bootstrap Documentation

Every skill includes instructions for:

• Humans following a guide
• AI agents executing commands
• Computer-use agents navigating browsers

Directory Structure

my-skill/
├── SKILL.md              # THE INTERFACE - agents read this
├── cmd/
│   └── my-skill/
│       └── main.go       # CLI entry point (cobra)
├── internal/
│   ├── config/
│   │   └── config.go     # XDG-compliant configuration
│   ├── db/
│   │   ├── schema.sql    # SQLite schema
│   │   └── queries.go    # Raw SQL queries (NO ORM!)
│   └── sync/
│       └── sync.go       # ETL from source
├── go.mod
├── go.sum
├── Makefile
└── .goreleaser.yaml      # Cross-platform releases

Quick Start

# Generate a new skill
./scripts/scaffold.sh my-skill "Short description" "🔧"

# Build and test
cd my-skill
go build ./cmd/my-skill
./my-skill init
./my-skill sync

The SKILL.md Contract

The SKILL.md file is the interface between the CLI tool and AI agents. It must include:

1. Frontmatter — Machine-readable metadata (name, install instructions)
2. Quick Start — 3-line getting started
3. Commands — Table of all commands
4. Output Formats — JSON examples
5. Bootstrap — Setup instructions for humans AND AI agents

See SKILL.md.template for the full format.

Why This Matters

From AI_POWER_EQUATION.md:

Alignment = Context × Intent

Skills are how agents get context about your world. The better the skill documentation:

• The faster agents can use tools
• The fewer errors they make
• The more autonomous they become

A well-documented skill is an alignment multiplier.

Skills Built With This Template

• eve — iMessage intelligence
• aix — AI session intelligence (coming soon)
• gog — Google Workspace

License

MIT