Skill Builder

Create Claude Code skills following proven patterns from mature skills (Linear, Governance).

Templates: templates/ Best Practices: BEST-PRACTICES.md GitHub Automation: scripts/create-repo.mjs

Quick Start

When user asks to create a skill:

1. Gather Basic Info

Ask the user:

• Skill name: Short, descriptive (e.g., "governance", "linear", "docker")
• Description: One sentence explaining when to use it
• Trigger phrases: What should activate this skill?
• Problem it solves: What does the user gain?

2. Provide Templates

Copy and customize these templates:

# Copy all templates to working directory
cp -r ~/.claude/skills/skill-builder/templates/* /path/to/new-skill/

3. Customize Files

Guide user through customizing:

1. skills/<name>/SKILL.md — Core skill definition
2. CHANGELOG.md — Version history
3. README.md — Installation and usage
4. package.json — Plugin metadata and topics

4. Publish to GitHub

Run the automation script:

node ~/.claude/skills/skill-builder/skills/skill-builder/scripts/create-repo.mjs \
  --name "<skill-name>-claude-skill" \
  --description "Claude Code skill for <purpose>" \
  --topics "claude,claude-code,claude-plugin,<domain-topics>"

Template-First Workflow

Step 1: Create Directory Structure

mkdir -p <skill-name>-claude-skill/skills/<skill-name>/scripts
mkdir -p <skill-name>-claude-skill/templates  # Optional

Step 2: Copy Core Templates

Step 3: Fill In Placeholders

All templates use these placeholders:

Curated Best Practices

From Linear Skill (Most Mature)

From Governance Skill

Universal Patterns

SKILL.md Structure

Every SKILL.md should have:

---
name: <skill-name>
description: <when to use, trigger phrases>
allowed-tools:
  - <tool1>
  - <tool2>
---

# <Skill Title>

One-line description.

> **Key Reference**: [link](path)

---

## Quick Start (First-Time Users)

1. Verify setup
2. Common operations
3. Getting help

---

## When This Skill Activates

### Trigger 1
What happens, what to check

### Trigger 2
What happens, what to check

---

## Core Patterns

Tables, examples, code blocks

---

## Anti-Patterns vs Correct Patterns

| Anti-Pattern | Correct Pattern | Why |
|--------------|-----------------|-----|
| ❌ Bad thing | ✅ Good thing | Reason |

---

## [Domain-Specific Sections]

...

---

## Related Documents

- [Link 1](path)
- [Link 2](path)

---

*Last updated: <date>*

package.json Structure

{
  "name": "claude-plugin-<skill-name>",
  "version": "1.0.0",
  "description": "<One sentence>",
  "keywords": [
    "claude",
    "claude-code",
    "claude-plugin",
    "<domain-specific>",
    "<domain-specific>"
  ],
  "author": "<github-username>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/<user>/<skill-name>-claude-skill.git"
  },
  "files": ["skills", "templates", "README.md", "LICENSE"],
  "scripts": {
    "setup": "node skills/<name>/scripts/setup.mjs",
    "check": "node skills/<name>/scripts/check.mjs"
  },
  "claude-plugin": {
    "name": "<Skill Title>",
    "description": "<Description for plugin registry>",
    "skills": ["skills/<name>"]
  }
}

GitHub Topics for Discoverability

Required Topics (all skills)

• claude
• claude-code
• claude-plugin

Domain Topics (choose relevant)

• governance, code-quality, standards
• project-management, issue-tracking
• testing, automation
• security, authentication
• database, api
• documentation, developer-tools

Publishing Checklist

Before publishing:

• SKILL.md has frontmatter (name, description, allowed-tools)
• SKILL.md has Quick Start section
• All placeholders replaced (no {{...}} remaining)
• No project-specific references (generic examples only)
• CHANGELOG.md has initial release with "Lesson Learned"
• README.md has installation instructions
• package.json has claude-plugin section
• LICENSE file exists (MIT)
• Topics include claude, claude-code, claude-plugin

Example: Creating a "Docker" Skill

# 1. Create structure
mkdir -p docker-claude-skill/skills/docker/scripts

# 2. Copy templates
cp ~/.claude/skills/skill-builder/templates/* docker-claude-skill/

# 3. Customize (example)
# - Replace {{SKILL_NAME}} with "docker"
# - Replace {{SKILL_TITLE}} with "Docker"
# - Add docker-specific patterns to SKILL.md

# 4. Publish
node ~/.claude/skills/skill-builder/skills/skill-builder/scripts/create-repo.mjs \
  --name "docker-claude-skill" \
  --description "Claude Code skill for Docker container development" \
  --topics "claude,claude-code,claude-plugin,docker,containers,devops"

Related Skills

• Linear Skill — Example of MCP integration, SDK automation
• Governance Skill — Example of documentation patterns, audit scripts
• Varlock Skill — Example of security-focused skill

Last updated: December 2025 Meta-skill for building Claude Code skills