Workflow for Creating a New Skill in the Claude-Skills Plugin: A 7-Step Development Guide

The workflow for creating a new skill in the claude-skills plugin involves seven distinct phases: proposing the skill, forking the repository, creating the SKILL.md file with proper front-matter, integrating it into SKILLS_GUIDE.md, testing locally via symlink development, running the validation script, and submitting a pull request.

The claude-skills plugin system, maintained in the Jeffallan/claude-skills repository, provides a structured framework for extending Claude Code's capabilities through modular, discoverable skills. Understanding the complete workflow for creating a new skill ensures your contribution follows established patterns for consistency, testing, and integration.

Phase 1: Propose Your Skill

Every new skill begins with validation and requirement gathering. According to the contribution guidelines in CONTRIBUTING.md, you must first describe the use case, target audience, core behavior, and example trigger phrases【/cache/repos/github.com/Jeffallan/claude-skills/main/CONTRIBUTING.md#L16-L22】. This phase ensures the skill fits the ecosystem before you write any code.

Phase 2: Fork and Set Up Your Environment

Create an isolated workspace by forking the repository and setting up a feature branch.

# Fork the repository on GitHub, then:

git clone https://github.com/your-user/claude-skills.git
cd claude-skills
git checkout -b feature/<your-skill>

Phase 3: Create the Skill Files

Directory Structure

Create your skill directory under skills/<skill-name>/. The minimum required file is SKILL.md, though complex skills may include a references/ folder for progressive-disclosure content【/cache/repos/github.com/Jeffallan/claude-skills/main/CONTRIBUTING.md#L84-L99】.

SKILL.md Front-Matter Schema

The SKILL.md file must include YAML front-matter defining the skill contract. As implemented in Jeffallan/claude-skills, the schema includes:

• name: Unique identifier for the skill
• description: Trigger conditions and keywords for invocation
• license: SPDX license identifier (e.g., MIT)
• metadata: Object containing author, version, triggers (comma-separated keywords), role, scope, output-format, domain, and related-skills

# Scaffold the skill directory and main file

mkdir -p skills/<your-skill>

cat > skills/<your-skill>/SKILL.md <<'EOF'
---
name: <your-skill>
description: Use when [triggering condition]. Invoke for [keywords].
license: MIT
metadata:
  author: https://github.com/your-user
  version: "1.0.0"
  triggers: keyword1, keyword2
  role: specialist
  scope: implementation
  output-format: code
  domain: backend
  related-skills: other-skill
---

# <Your Skill Name>

[One-sentence role definition]

## Role Definition

...

## Core Workflow

1. **Step 1** – …
2. **Step 2** – …
3. **Step 3** – …

## Reference Guide

| Topic | Reference | Load When |
|-------|-----------|-----------|
| Example | `references/example.md` | Trigger phrase |
EOF

Phase 4: Integrate Into the Knowledge Base

To make your skill discoverable, add an entry to SKILLS_GUIDE.md under the appropriate category (e.g., Critical Thinking or Backend Development). The guide uses a specific markdown table format for category placement and decision trees【/cache/repos/github.com/Jeffallan/claude-skills/main/SKILLS_GUIDE.md#L92-L100】.

Phase 5: Test Locally Using the Symlink Workflow

Claude Code loads plugins from a cache directory. The symlink development workflow described in docs/local_skill_development.md allows you to test changes without publishing【/cache/repos/github.com/Jeffallan/claude-skills/main/docs/local_skill_development.md#L5-L15】.

# Find the cached version path

cat ~/.claude/plugins/installed_plugins.json | grep installPath

# Backup the cached copy

mv ~/.claude/plugins/cache/<plugin>/<name>/<version> \
   ~/.claude/plugins/cache/<plugin>/<name>/<version>.bak

# Symlink your working copy

ln -s $(pwd)/skills/<your-skill> \
   ~/.claude/plugins/cache/<plugin>/<name>/<version>

Restart Claude Code, invoke the skill using your defined triggers, and verify that examples execute correctly.

Phase 6: Validate Your Skill

Run the built-in validator to catch YAML syntax errors, schema violations, reference routing issues, and file-size limits before submitting to CI:

python scripts/validate-skills.py --skill <your-skill>

The validation script is referenced in the contribution workflow and enforces repository standards【/cache/repos/github.com/Jeffallan/claude-skills/main/CONTRIBUTING.md#L62-L68】.

Phase 7: Submit Your Pull Request

Commit your changes using the conventional prefix Add: for new skills, then push and open a PR:

git add .
git commit -m "Add: <your-skill> – <short description>"
git push origin feature/<your-skill>

Include the motivation, usage examples, and any related issue numbers in your pull request description.

Summary

• Propose first: Document your skill idea in CONTRIBUTING.md before coding.
• Structure matters: Place your SKILL.md in skills/<skill-name>/ with complete YAML front-matter including triggers, role, and metadata.
• Test locally: Use the symlink workflow to point Claude Code's cache at your working copy without publishing.
• Validate early: Run scripts/validate-skills.py to catch schema errors before CI.
• Integrate fully: Update both SKILLS_GUIDE.md for discoverability and follow the Add: commit convention for PRs.

Frequently Asked Questions

What is the minimum required file to create a new skill?

The only mandatory file is SKILL.md placed inside a directory named after your skill under skills/<skill-name>/. This file must contain valid YAML front-matter defining the skill name, description, license, and metadata including triggers and role. Optional references/ folders can be added for skills requiring progressive disclosure of complex information.

How do I test my skill without publishing it to the registry?

Use the symlink development workflow documented in docs/local_skill_development.md. Backup the cached version in ~/.claude/plugins/cache/ and create a symbolic link pointing to your local working copy at skills/<your-skill>. Restart Claude Code to load your local version, allowing you to test triggers and examples in real-time without pushing to GitHub.

What validation does the validate-skills.py script perform?

The validator enforces repository standards by checking YAML syntax correctness, front-matter schema compliance (required fields like name, description, metadata), reference routing accuracy (ensuring linked files in references/ exist), and file-size limits to prevent bloated skills. Run python scripts/validate-skills.py --skill <skill-name> to catch errors before CI rejects your pull request.

Where should I add my skill to make it discoverable by users?

You must register your skill in SKILLS_GUIDE.md under the appropriate category section (such as Critical Thinking, Backend Development, or Data Science). This file serves as the central catalog and uses a specific markdown table format for category placement, decision trees, and quick-reference entries, ensuring users can find your skill when browsing the knowledge base.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}