Open source

Know something?
Teach it to Claudia.

Contributing means writing a markdown file. That's it. If you can explain something about technology, you can make Claudia smarter.

Pick your level

Write what you know

Drop a markdown file in any references/ folder. Know a lot about Redis? Write about Redis. That's the whole contribution.

~30 min

Teach her to catch mistakes

Add patterns to the hook scripts. If you've seen a common mistake, teach Claudia to catch it for everyone.

~1 hour

Make a topic deeper

Pick a domain Claudia already knows and make her advice better. Add examples, edge cases, real-world gotchas.

~2 hours

Add a whole new topic

Use the scaffolding tool to create a full knowledge domain. Own a subject — architecture, mobile, ML, whatever you know.

~4 hours

Build a new automatic check

Write a script that catches an issue every time Claude writes a file. Security, quality, accessibility — anything that should never slip through.

~4 hours

Quick start

git clone https://github.com/reganomalley/claudia.git
cd claudia
./scripts/create-domain.sh mobile
# Now just write markdown in skills/claudia-mobile/
# That's literally it. Open a PR when you're done.

How to write for Claudia

Have an opinion

Don't say 'it depends.' Say what you'd actually use, then explain the tradeoffs so people can disagree.

Lead with the answer

Put the recommendation first. Then the reasoning. People are here because they need to make a decision, not learn the theory.

Say when NOT to use it

Every tool breaks somewhere. Saying where builds trust and saves people hours of debugging the wrong choice.

Use tables and decision trees

A comparison table is worth a thousand words. If someone is choosing between two things, make a table.

Keep it tight

The main file loads into Claude's memory every time. Keep it under 2000 words. Put deep dives, reference tables, and long examples into the references/ folder — those only load when needed.

Before you contribute

Hooks run on real machines

Claudia's hook scripts execute locally with the same permissions as Claude Code. A malicious hook could read files, exfiltrate data, or modify code silently. We take this seriously.

Rule

All hook and script PRs require maintainer review. Markdown-only contributions to references/ are lower risk, but hooks touch every user's machine.

Rule

No network calls in hooks. Hook scripts must never fetch URLs, phone home, or access anything outside the local filesystem.

Rule

No obfuscated code. Every line should be readable. If a reviewer can't understand what a script does, it doesn't ship.

How

Hook PRs get a dedicated security review. We diff every line against the existing script, check for exfil patterns, and test in a sandboxed environment before merging.

Testing

212+ tests and CI

Every hook has unit tests. CI runs on every push and PR against Python 3.9 and 3.12. If you're adding or modifying a hook, run the suite locally before opening a PR: 

pip install pytest
pytest tests/ -v
# 212 passed in ~3 seconds

Tests use subprocess execution — the same way Claude Code runs hooks. No mocking of the scripts themselves.

Start contributing