# How to Contribute New Skills to the emilkowalski/skills Project

> Learn to contribute new skills to the emilkowalski/skills project. Follow our guide to add skills, create documentation, and update the README for your contributions.

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: how-to-guide
- Published: 2026-08-09

---

**To contribute new skills to the emilkowalski/skills project, create a folder under `skills/`, populate it with a [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file containing YAML front-matter and an opinionated workflow guide, optionally add supporting files like [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md), and update the root [`README.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file.

### SKILL.md Structure

The [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) or [`skills/pick-ui-library/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) – Code snippets and implementation examples
- [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) – Structured templates for audits or planning sessions

These files live alongside [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) if your skill requires concrete implementation examples.

5. **Update the Reference table** in the root [`README.md`](https://github.com/emilkowalski/skills/blob/main/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:

```markdown
---
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`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) file in the same folder:

```markdown

# 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`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) with YAML front-matter (`name`, `description`) and an opinionated workflow guide
- Optionally add supporting files like [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) for implementation examples
- Update the Reference table in the root [`README.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file. You may optionally include ancillary files like [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) or [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/README.md) file to include a link to your new [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) for concrete examples of the expected style.