skills: Instructions file for Codex

How to add new skills and rules

This guide explains how to structure and add new skills to this repository.

Skill structure

Each skill should follow this structure:

skills/
└── knock-your-skill-name/
    ├── SKILL.md          # Human-readable guide (required)
    └── rules/            # Rule files directory (required)
        ├── rule-1.md
        ├── rule-2.md
        └── ...

Step-by-step guide

1. Create the skill directory

Create a new directory under skills/ with a descriptive name using the knock- prefix and kebab-case:

mkdir -p skills/knock-your-skill-name/rules

2. Create rule files

Add individual rule files in the rules/ directory. Each rule file should:

• Use markdown format (.md)
• Include frontmatter with metadata:

  ---
  title: Your rule title
  description: Brief description of the rule
  tags:
    - relevant-tag-1
    - relevant-tag-2
  category: knock-your-skill-name
  last_updated: YYYY-MM-DD
  ---
  

• Use sentence case for all titles and headings
• Be focused on a single topic or theme
• Include examples and practical guidance

Example rule file structure:

---
title: Rule name in sentence case
description: What this rule covers
tags:
  - tag1
  - tag2
category: knock-your-skill-name
last_updated: 2026-01-23
---

# Rule name in sentence case

## Section heading

Content here...

### Subsection

More content...

3. Create SKILL.md

Create a SKILL.md file that serves as a human-readable guide. It should:

• Provide an overview of the skill
• Explain how to use the different rules
• Reference rule files using relative paths (e.g., rules/rule-1.md)
• Include quick reference sections
• Use sentence case for all headings

Example SKILL.md structure:

---
name: knock-your-skill-name
description: Brief description of what this skill provides.
---

# Your skill name

Brief description of what this skill provides.

## Overview

List the rule files and what they cover.

## How to use this skill

### For specific use case 1

1. **Start with rule X** (`rules/rule-x.md`)
   - What to look for
   - Key principles

2. **Check rule Y** (`rules/rule-y.md`)
   - Additional considerations

## Rule files reference

- `rules/rule-1.md` - Description
- `rules/rule-2.md` - Description

## Quick reference

Key points and patterns...