build-a-skill

Build a Skill

Use this skill when creating or updating a skill that must work with askill CLI and registry conventions.

Authoring Standard

A valid skill requires one entry file:

• SKILL.md (required)

Optional supporting files:

• scripts/ for executable commands
• assets/ for templates or reference material

Recommended layout:

my-skill/
├── SKILL.md
├── scripts/
│   └── main.js
└── assets/

Minimal SKILL.md Template

---
name: my-skill
slug: my-skill
description: One-line purpose of the skill
version: 0.1.0
---

# My Skill

## Overview
What this skill does and when to use it.

## Usage
Step-by-step instructions the agent can execute.

Frontmatter Rules

Required:

• name - lowercase letters/numbers/hyphens only
• description - concise summary

Strongly recommended:

• version - valid semver (1.0.0, 1.1.0-beta.1)
• slug - publish identifier (@author/slug)

Optional:

• author, tags, dependencies, commands, repository, license

Dependencies format:

• Published: @author/skill-name or @author/skill-name@^1.2.0
• Indexed GitHub: gh:owner/repo@skill-name or gh:owner/repo/path

Commands format:

commands:
  analyze:
    run: node scripts/analyze.js
    description: Analyze current repository
  _setup:
    run: npm ci
    description: Install command dependencies

Write for Agents, Not Humans

Your markdown body should be executable guidance:

• include clear preconditions
• include exact commands
• include expected outputs/artifacts
• include failure handling and recovery paths

Good instruction pattern:

1. Check prerequisites
2. Run command
3. Verify output
4. Handle common failures

Development Loop (Local)

Use this loop while building:

# 1) scaffold
askill init ./my-skill

# 2) validate schema/fields
askill validate ./my-skill/SKILL.md

# 3) install locally for testing
askill add ./my-skill -a claude-code -y

# 4) run commands
askill run my-skill:<command>

# 5) inspect installed state
askill list