How to Create a Custom Claude Code Skill

Example 2: A multi-file skill with a reference file and a script

Skills can grow beyond one file. A skill can include supplemental material, such as a REFERENCE.md, and executable code. Claude Code can also install packages from standard repositories like PyPI and npm when a skill needs them. The script below uses only the Python standard library, so no installation is needed.

This skill reviews a codebase for leftover work markers. The layout is:

.claude/skills/todo-audit/
├── SKILL.md
├── REFERENCE.md
└── scripts/
    └── find_todos.py

First, the script scripts/find_todos.py:

import re
import sys
from pathlib import Path

PATTERN = re.compile(r"(TODO|FIXME|HACK)[:\\s]*(.*)")
SKIP_DIRS = {".git", "node_modules", ".venv", "__pycache__", "dist"}


def scan(root):
    for path in root.rglob("*"):
        if not path.is_file() or SKIP_DIRS & set(path.parts):
            continue
        try:
            text = path.read_text(encoding="utf-8")
        except (UnicodeDecodeError, OSError):
            continue
        for number, line in enumerate(text.splitlines(), start=1):
            match = PATTERN.search(line)
            if match:
                yield path, number, match.group(1), match.group(2).strip()


def main():
    root = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    count = 0
    for path, number, tag, note in scan(root):
        print(f"{path}:{number} [{tag}] {note}")
        count += 1
    print(f"Total: {count}")


if __name__ == "__main__":
    main()

Next, REFERENCE.md, which holds the rules for how to rank findings. Keeping this out of SKILL.md means Claude only reads it when it needs it:

# Severity reference

- **FIXME** in code on a request path (API handlers, auth, payments): high.
- **FIXME** elsewhere: medium.
- **HACK**: medium. Ask whether a proper fix is feasible.
- **TODO** with no owner or ticket: low.
- Markers inside tests or docs: low, unless they say a test is disabled.

Finally, SKILL.md:

---
name: todo-audit
description: Audits a codebase for TODO, FIXME and HACK comments and ranks them by severity. Use when the user asks for a TODO audit, leftover work, tech debt markers, or "what is unfinished in this repo".
---

# TODO audit

## Steps

1. Run the bundled script from this skill's folder: `python scripts/find_todos.py .`
2. Read `REFERENCE.md` and rank every finding by severity.
3. Open the surrounding code for any high-severity item to confirm it is real.
4. Report a table with columns: severity, file:line, marker, note.

## Rules

- Do not edit files. This skill only reports.
- If the script prints `Total: 0`, say that no markers were found.

Result: when you ask "what is unfinished in this repo?", Claude runs the script, reads the reference, and returns a ranked table such as src/api/auth.py:42 | high | FIXME | token expiry not checked. The deterministic scanning is done by code, and Claude only does the judgment work.

Testing and improving a skill

Treat a skill like any other piece of code and test it in two ways:

• Direct invocation: run /skill-name and check that the output follows your instructions.
• Automatic selection: phrase a request naturally, without the slash command, and see whether the skill is chosen.

If a skill does not trigger, rewrite the description first. Add the phrases your team actually says, and state the situation in which the skill applies. If a skill triggers too often, narrow the description. If the output is inconsistent, add a template or a short example to the instructions.

Keep each skill focused. If SKILL.md keeps growing, move stable details into files like REFERENCE.md and link to them from the instructions.

Sharing the skill

For team use, commit .claude/skills/ to the repository. For personal use across projects, copy the folder to ~/.claude/skills/.

The same SKILL.md format also works in claude.ai, the Claude API, and other tools that adopted the Agent Skills standard. For claude.ai, package the skill folder as a ZIP file and upload it under Customize > Skills, where uploaded skills can be toggled on or off.

Conclusion

A custom skill is a folder, a SKILL.md file with a precise description, and clear instructions. Start with instructions only, as in the pr-description example, and add reference files or scripts when the task needs deterministic work, as in todo-audit.

The quality of a skill comes down to focus and testing. Pick one repeatable workflow, write the description in the words users really use, and check both slash-command and automatic invocation before sharing it with your team.