skill

CLI for creating and validating Claude Agent Skills.

flowchart LR
    A[skill new] --> B[SKILL.md]
    B --> C[skill validate]
    C --> D{Valid?}
    D -->|Yes| E[Ship it]
    D -->|No| F[Fix errors]
    F --> C

Install

go install github.com/intent-solutions-io/create-agent-skill-md@latest

Quick Start

# Create a new skill (interactive wizard)
skill new my-skill

# Or non-interactive
skill new my-skill -d "Does X. Use when Y." -y

# Validate it
skill validate ./my-skill

What's a SKILL.md?

---
name: my-skill
description: Does something useful. Use when you need X.
---

# My Skill

## Instructions
1. Do this
2. Then that

## Examples
Input: "make it work"
Output: it works

That's it. Name + description in frontmatter, instructions in markdown body.

Commands

Validation

flowchart TD
    subgraph Errors[Errors - Must Fix]
        E1[Missing SKILL.md]
        E2[Missing name/description]
        E3[Bad name format]
    end
    subgraph Warnings[Warnings - Should Fix]
        W1[Missing 'Use when...' pattern]
        W2[Missing sections]
        W3[Name doesn't match directory]
    end

Rules at a Glance

Errors (skill won't work):
- Must have SKILL.md with YAML frontmatter
- name: lowercase, hyphens, numbers only (max 64 chars)
- description: required (max 200 chars, no XML tags)

Warnings (skill works, but could be better):
- Description should say "Use when..."
- Should have ## Instructions and ## Examples sections
- Directory name should match skill name

CI/CD

# JSON output for automation
skill validate --json ./my-skill

# Strict mode (warnings = errors)
skill validate --strict ./my-skill

Exit codes: 0 = valid, 1 = errors, 2 = system error

Shell Completion

# Bash
source <(skill completion bash)

# Zsh
skill completion zsh > "${fpath[1]}/_skill"

# Fish
skill completion fish > ~/.config/fish/completions/skill.fish

License

Apache 2.0