Contributing to ctf-skills

Contributing to ctf-skills

Thanks for helping expand the CTF skills collection. This guide covers how to set up your environment, add techniques, create new skill categories, and get your PR merged.

Development Setup

Prerequisites

• Python 3.12+
• Node.js (for markdownlint)
• pre-commit

Install pre-commit hooks

pip install pre-commit
pre-commit install

This installs hooks that run automatically on every commit:

• trailing-whitespace and end-of-file-fixer — basic formatting
• check-yaml — validates YAML files
• check-added-large-files — prevents accidental binary commits
• ruff — Python linter and formatter (for files in scripts/)
• shellcheck — static analysis for shell scripts
• markdownlint-cli2 — Markdown linter (all .md files)

Install test dependencies

pip install pytest

Adding Techniques to an Existing Skill

This is the most common contribution. Each skill category (e.g., `ctf-web`, `ctf-crypto`) has a `SKILL.md` and one or more supporting technique files.

1. Choose the right file

Look at the existing technique files in the skill directory. For example, `ctf-web/` has files like `sql-injection.md`, `server-side.md`, `client-side.md`, etc. Add your technique to the file that best matches its topic. If no file fits, you can create a new one.

2. Follow the technique format

Technique files use this structure:

## Technique Name (Optional CTF/Year Attribution)

Brief description of when and why to use this technique.

```language
# Working payload or code example
# Use realistic but safe placeholder targets (example.com, attacker.com)
```

**Key insight:** One or two sentences explaining the core idea.

Conventions:

• Start each technique with an h2 (##) heading
• Include working code examples in fenced code blocks with a language tag
• Use placeholder hostnames (example.com, attacker.com) — never real infrastructure
• Attribute the source CTF/competition in the heading when known
• Keep explanations concise — this is a quick reference, not a tutorial

3. Update the SKILL.md

After adding a technique, update the parent `SKILL.md`:

• Add the technique to the Additional Resources list if you modified an existing file
• If you created a new technique file, add a new entry to the list with a relative link

4. Update the README table

Update the skill's row in `README.md`: increment the **Files** count if you added a new file, and add the technique name to the **Description** column.

Creating a New Skill Category

A new skill category is a directory at the repo root containing at minimum a `SKILL.md` file.

The `SKILL.md` must have YAML frontmatter with these required fields:

---
name: ctf-newcategory
description: >-
  Provides [category] techniques for CTF challenges. Use when [trigger conditions].
license: MIT
compatibility: Requires filesystem-based agent (Claude Code or si