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

> Master the workflow for creating a new skill in the claude-skills plugin with this 7-step development guide. Learn proposal to pull request and contribute effectively.

- Repository: [Jeffallan/claude-skills](https://github.com/jeffallan/claude-skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/Jeffallan/claude-skills/blob/main/SKILL.md) file with proper front-matter, integrating it into [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.

```bash

# 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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`

```bash

# 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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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】.

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/Jeffallan/claude-skills/blob/main/CONTRIBUTING.md) before coding.
- **Structure matters**: Place your [`SKILL.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/scripts/validate-skills.py) to catch schema errors before CI.
- **Integrate fully**: Update both [`SKILLS_GUIDE.md`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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`](https://github.com/Jeffallan/claude-skills/blob/main/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.