How to Contribute New Skills to the emilkowalski/skills Project

To contribute new skills to the emilkowalski/skills project, create a folder under skills/, populate it with a SKILL.md file containing YAML front-matter and an opinionated workflow guide, optionally add supporting files like RECIPES.md, and update the root README.md Reference table before opening a pull request.

The emilkowalski/skills repository maintains a curated collection of self-contained markdown specifications that define design and engineering workflows. Because the project consists entirely of markdown files with no build steps or runtime dependencies, contributing new skills requires only adding properly structured documentation to the repository.

Repository Architecture

The project uses a flat catalog structure where all skill definitions reside as markdown documents under version control.

The skills/ Directory

Each skill occupies its own folder directly under skills/, following the naming convention skills/<skill-name>/. This flat layout eliminates deep nesting and makes skills immediately discoverable. According to the repository structure, the folder must contain at minimum a SKILL.md file.

SKILL.md Structure

The SKILL.md file serves as the core definition. It begins with YAML front-matter specifying the skill's name and description, followed by an opinionated markdown guide. The body typically includes sections like Operating Posture, Hard Rules, and Step-by-Step Guide that prescribe specific decision-making flows. For reference, examine skills/animate/SKILL.md or skills/pick-ui-library/SKILL.md to see the expected formatting and tone.

Optional Supporting Files

Skills can include ancillary markdown files that provide concrete implementations without cluttering the core definition. Common patterns include:

• RECIPES.md – Code snippets and implementation examples
• PLAN-TEMPLATE.md – Structured templates for audits or planning sessions

These files live alongside SKILL.md in the skill folder and are referenced via relative links.

Step-by-Step Contribution Workflow

Follow these steps to ensure your skill integrates properly with the existing catalog.

1. Fork the repository to create your own copy with write access.

2. Create the skill folder at skills/<your-skill-name>/ to isolate your contribution.

3. Write the SKILL.md file using the template structure found in existing skills. Include the required YAML front-matter with name and description fields, and maintain an opinionated, prescriptive tone throughout the guide.

4. Add supporting files (optional) such as RECIPES.md if your skill requires concrete implementation examples.

5. Update the Reference table in the root README.md to include a row linking to your new skills/<your-skill-name>/SKILL.md. This registration step makes the skill visible to users and the skills CLI tooling.

6. Submit a Pull Request against the main branch for maintainer review.

7. Respond to feedback by incorporating any requested style or content changes.

SKILL.md Template

Use the following structure when authoring your skill definition:

---
name: your-skill-name
description: Short one-sentence summary of what the skill does
---

# Human-Readable Title

A concise introduction explaining **why** the skill exists and **when** to invoke it.

## Operating Posture

Explain the perspective the skill assumes (e.g., "You are a senior design engineer...").

## Hard Rules

1. **Rule 1** – The most important invariant.
2. **Rule 2** – Secondary constraint.

## Step-by-Step Guide

1. **Step 1** – Initial assessment criteria.
2. **Step 2** – Decision tree or evaluation gate.
3. **Step 3** – Implementation advice or code snippets.

## Recipes

Reference reusable snippets here or link to an auxiliary `RECIPES.md`.

## Output

State exactly what the skill should emit (e.g., code, configuration, or summary).

## Tone

Brief, opinionated, and direct.

Adding Supporting Documentation

When skills require concrete implementation examples, create a RECIPES.md file in the same folder:

# Recipes for your-skill-name

## Example 1 – Specific use case

```js
// Implementation code following the skill's hard rules

Example 2 – Alternative scenario

...

Reference this file from your main [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) to keep the core definition concise while offering ready-made implementations.

## Updating the Root README

The [`README.md`](https://github.com/emilkowalski/skills/blob/main/README.md) at the repository root contains a Reference table listing all available skills. You must append a new row linking to your skill's markdown file:

```markdown
| Skill | Description |
|-------|-------------|
| existing-skill | Existing description |
| your-skill-name | [Link](skills/your-skill-name/SKILL.md) |

This registration ensures the skill appears in the public index and can be discovered by the skills CLI.

Summary

• Create a new folder under skills/<skill-name>/ for your contribution
• Include a SKILL.md with YAML front-matter (name, description) and an opinionated workflow guide
• Optionally add supporting files like RECIPES.md for implementation examples
• Update the Reference table in the root README.md to register the skill
• Submit changes as a pull request against the main branch
• No build steps, dependencies, or CI configuration are required—contributions are pure markdown

Frequently Asked Questions

What file structure is required for a new skill?

Create a folder under skills/<skill-name>/ containing at minimum a SKILL.md file. You may optionally include ancillary files like RECIPES.md or PLAN-TEMPLATE.md. The flat structure keeps skills self-contained and discoverable without deep nesting.

Does the project require any build steps or dependencies?

No. The emilkowalski/skills repository consists entirely of markdown files. Contributions require only editing or adding markdown documentation—no compilation, dependency installation, or CI pipeline configuration is necessary.

How do I make my new skill appear in the CLI and documentation?

You must update the Reference table in the root README.md file to include a link to your new SKILL.md. The YAML front-matter in your skill file (name and description fields) provides the metadata used by tooling to identify and describe the skill.

What tone and style should I use when writing a skill?

Write in a brief, opinionated, and direct voice. Include a Hard Rules section that prescribes specific invariants, an Operating Posture that defines the assumed perspective, and a Step-by-Step Guide that provides concrete decision-making flows. Reference existing skills like skills/animate/SKILL.md for concrete examples of the expected style.

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