Tutorial: Author your own skill

The Author stage is where you give back. You have used Skillsmith to find and install other people's skills; now you scaffold, validate, and publish your own. The end-to-end path is CLI-led — that is intentional: authoring is filesystem-heavy, and the CLI is the cleanest tool for the job.

These tutorials show Skillsmith in Claude Code. For installation in your preferred runtime (Cursor, Continue, Copilot, Windsurf), see Getting Started.

What you will do

• Scaffold a new skill directory from a template
• Edit SKILL.md to define trigger phrases and instructions
• Validate the structure before publishing
• Publish the skill to the Skillsmith registry
• Generate a companion subagent if your skill needs one
• Convert an existing prompt into a skill (transform)
• Scaffold a custom MCP server for skills that need backend logic

The six author subcommands

Skills follow Anthropic's SKILL.md format and work in any MCP-capable runtime. The author tooling itself is universal; we use Claude Code below only because it is the most common runtime for testing your skill once it is scaffolded.

Step 1 — Choose your scaffold

create and author init overlap; the difference is destination and depth.

Scaffolding interactively

Run this in your terminal:

skillsmith create my-awesome-skill

The CLI prompts for description, author, category, skill type, and behavioral classification. Hit enter on defaults if you are unsure; everything is editable in the generated SKILL.md.

Scaffolding non-interactively

For scripted scaffolding (CI, onboarding scripts):

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

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

Step 2 — Edit SKILL.md

The scaffold writes a SKILL.md with TODO markers. The two fields that matter most for discoverability are description (which runtimes match against user prompts) and the trigger phrases embedded in it.

---
name: my-awesome-skill
description: Automates code review checklists. Use when reviewing pull requests, running pre-merge checks, or auditing code quality. Triggers on phrases like "review this PR", "check this code", "audit before merge".
author: myusername
version: 0.1.0
category: development
---

# My Awesome Skill

Instructions for the agent...

Behavioral classification

Skills scaffolded with create include a behavioral classification: guided (interactive, asks the user questions), autonomous (runs through to completion without asking), or reactive (responds to a specific trigger then stops). Pick the one that best describes your skill's behavior.

Step 3 — Validate

Validation catches the common authoring mistakes — missing frontmatter fields, broken bundle references, malformed YAML — before publish rejects them.

Run this in your terminal:

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

Or via the MCP from Claude Code: "Validate my skill at ~/.claude/skills/my-awesome-skill".

The validator checks:

• SKILL.md exists and parses as valid YAML frontmatter
• Required fields: name, description, author, version
• Referenced bundle files (scripts, assets) actually exist on disk
• Trigger phrases present in description
• License header where required (Elastic 2.0, MIT, Apache, etc.)

Step 4 — Publish to the registry

Publishing generates a checksum manifest, packages the skill bundle, and submits to the Skillsmith registry. New skills enter at the unverified trust tier and graduate to community once they pass a basic security scan and carry the required metadata.

Run this in your terminal:

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

The first publish from your account requires a logged-in CLI session — run skillsmith login if you have not already. Subsequent publishes inherit that session.

After publish, the skill appears in search within the next indexing cycle (within ~6 hours). You can verify via Discover: "Search for my-awesome-skill".

Step 5 — Generate a companion subagent (optional)

If your skill is autonomous and needs to run as a Claude Code subagent (separate context window, separate tool permissions), generate the subagent definition:

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

This emits an agent definition under ~/.claude/agents/<name>.md that mirrors the skill's trigger phrases. Useful when the skill needs to operate without polluting the main conversation context.

Step 6 — Transform an existing prompt into a skill

If you have an existing instructions document, system prompt, or README you want to convert into a properly structured skill, the transform subcommand does the heavy lifting.

skillsmith author transform ./my-prompt.md -o ~/.claude/skills/my-skill

The transformer extracts trigger phrases, derives a description, scaffolds the SKILL.md frontmatter, and copies the instructions content. Always follow up with author validate — the transformer is a starting point, not a final answer.

Step 7 — Scaffold a custom MCP server (advanced)

Some skills need backend logic that cannot live in SKILL.md alone — a database query, an API call, a long-running computation. The mcp-init subcommand scaffolds a TypeScript MCP server that your skill can call into.

skillsmith author mcp-init my-skill-mcp

This is an advanced path. Most skills do not need a custom MCP server — they work fine in pure SKILL.md form. Reach for mcp-init only when you have verified the skill cannot be expressed declaratively.

Common pitfalls

"Skill name already taken"

Skill names are unique per author. community/my-skill is yours forever; if someone else has otherauthor/my-skill, that does not collide. Pick descriptive, qualified names — generic names like helper trip the namespace audit even after publish.

Publish rejects with "missing trigger phrases"

The description field needs explicit trigger phrasing. The publisher runs the same heuristic as the namespace audit — descriptions without recognizable triggers are rejected to keep the registry's discoverability signal high.

Validation passes locally but publish fails

The most common cause is a missing license header. Check LICENSE at the skill root; the publisher will refuse to submit a skill without one.

Where to next

Your skill is published. Now monitor it: the Govern stage covers audit logs and install metrics if you operate at team scale, and Maintain applies once you start iterating on your published skill.

Reference: CLI reference · Trust Tiers · SKILL.md format.

Previous: Maintain — Next: Govern