Skill Authoring

Create, validate, and publish reusable Claude Code skills with the Skillsmith CLI.

Overview

The Skillsmith CLI offers two paths for creating skills:

Quick Start

Create a skill, customize it, validate, and publish in four steps:

# 1. Scaffold a new skill
skillsmith create my-awesome-skill

# 2. Edit the generated SKILL.md
#    ~/.claude/skills/my-awesome-skill/SKILL.md

# 3. Validate your skill
skillsmith author validate ~/.claude/skills/my-awesome-skill

# 4. Prepare for publishing
skillsmith author publish ~/.claude/skills/my-awesome-skill

The create command runs interactively by default, prompting for description, author, category, skill type, and behavioral classification. You can also pass these as flags for non-interactive usage:

skillsmith create my-awesome-skill \
  --description "Automates code review checklists" \
  --author myusername \
  --category development \
  --type basic \
  --behavior guided

Use --dry-run to preview the scaffold output without writing any files.

Behavioral Classification

Skills created with skillsmith create include a behavioral classification section that tells users what to expect when they run your skill.

Skill Types

Behavioral Modes

Validation

Run skillsmith author validate <path> to check your skill before publishing. The path can be a directory containing SKILL.md or a direct path to the file.

# Validate a skill directory
skillsmith author validate ~/.claude/skills/my-awesome-skill

# Validate the current directory
skillsmith author validate .

The validator checks:

• SKILL.md presence — the file must exist in the skill directory
• YAML frontmatter — valid YAML between --- delimiters
• Required fields — name, description, and version must be present
• Metadata parsing — author, tags, category, and other fields are parseable
• Trust tier inference — the validator reports the inferred trust tier based on skill metadata

Validation output includes parsed metadata (name, description, author, version, tags, trust tier) and all frontmatter fields, so you can verify everything looks correct before publishing.

Publishing

When your skill is ready to share, use skillsmith author publish <path> to prepare it for distribution.

skillsmith author publish ~/.claude/skills/my-awesome-skill

The publish command:

1. Validates your skill (publishing fails if validation fails)
2. Generates a SHA-256 checksum of your SKILL.md
3. Writes a .skillsmith-publish.json manifest with name, version, checksum, and trust tier

After running publish, share your skill through one of these methods:

GitHub (Recommended)

# Push to a GitHub repository
gh repo create my-awesome-skill --public
cd ~/.claude/skills/my-awesome-skill
git init && git add . && git commit -m "feat: initial skill"
git remote add origin https://github.com/yourusername/my-awesome-skill
git push -u origin main

# Create a release
gh release create v1.0.0 --title "v1.0.0" --notes "Initial release"

# Add the topic "claude-skill" to your repository for automatic discovery

Manual Installation

Share the skill directory directly. Users copy it to ~/.claude/skills/.

Archive

tar -czf my-awesome-skill.tar.gz -C ~/.claude/skills my-awesome-skill

Reference Scanning

Use --check-references to scan for project-specific references that might leak internal details before publishing:

skillsmith author publish . --check-references

You can also supply custom regex patterns with --reference-patterns:

skillsmith author publish . --check-references --reference-patterns "JIRA-\d+,internal-api"

Trust Tier Progression

Published skills progress through trust tiers as they gain community adoption:

See Trust Tiers for details on the progression criteria.

Advanced Commands

skillsmith author subagent

Generate a companion subagent definition for your skill. Subagents allow your skill to delegate tasks to specialized agents with specific tool permissions.

# Generate a subagent for a skill
skillsmith author subagent ~/.claude/skills/my-awesome-skill

The command reads your SKILL.md, analyzes tool requirements, and generates a subagent configuration alongside a CLAUDE.md snippet for integration.

skillsmith author transform

Upgrade an existing skill by generating a subagent configuration. This is non-destructive — it adds new files without modifying your existing SKILL.md.

# Transform a single skill
skillsmith author transform ~/.claude/skills/my-skill

# Transform all installed skills (batch mode)
skillsmith author transform --batch

# Preview changes without writing files
skillsmith author transform ~/.claude/skills/my-skill --dry-run

skillsmith author mcp-init

Scaffold an MCP server project alongside your skill. This creates a complete MCP server with proper project structure, tool definitions, and configuration.

skillsmith author mcp-init my-mcp-server

Skill Structure Reference

A fully scaffolded skill (created with skillsmith create) has this structure:

my-skill/
├── SKILL.md           # Main skill file (required)
├── README.md          # Documentation
├── CHANGELOG.md       # Version history
├── .gitignore         # Git ignore rules
├── resources/         # Supporting files (data, templates, etc.)
└── scripts/           # Automation scripts (optional, use --scripts)

Skills created with skillsmith author init include SKILL.md, README.md, .gitignore, resources/, and scripts/ but omit the CHANGELOG.md and behavioral classification section.

SKILL.md Frontmatter Fields

Next Steps

• CLI Reference — Full list of all CLI commands and flags
• Trust Tiers — How skills are reviewed and promoted
• Security — Skill security model and protections
• Configuration Guide — Set up API keys for publishing