MegaBadCoder Document
Documentation is code's second user-facing surface. Treat it with the same care.
Scope — when this skill applies
- Project documentation (
README.md,docs/**/*.md) - CLAUDE.md / AGENTS.md / GEMINI.md instructions
- SKILL.md files for skill packs
- In-code docstrings (classes, modules)
- Inline code comments
Core rules — apply to every form of documentation
Project docs (README.md, docs/) — answer four questions
Keep READMEs under 200 lines. More than that → split into docs/.
CLAUDE.md / AGENTS.md — project-wide agent guidance
- Principles and constraints that apply across the project
- One-line style preferences ("no markdown tables unless asked")
- Pointers to key files or scripts
- What NOT to do (often more useful than what to do)
Do not write per-task instructions here. Those belong in docs/tasks/<slug>.md.
SKILL.md — the frontmatter is load-bearing
- Frontmatter:
name,description. Thedescriptionis the auto-trigger signal — make it specific and action-oriented. - Short body: when to use, process, key rules, terminal state.
- Section headers should summarize the section. A reader who skims headers should know the gist.
- Target under ~150 lines. A skill the agent won't read is worse than no skill.
In-code docstrings — for large classes and modules, describe responsibility AND non-responsibility
Every large class or module gets a docstring explaining what it's responsible for and what it is not:
class DatasetBuilder:
"""Build dataset shards from raw episodes.
Responsibilities:
- Orchestrate download → process → encode → verify stages
- Persist per-episode progress for restart
- Validate schema at stage boundaries
Not responsibilities:
- Training-time data loading (see training/loader.py)
- Cloud sync (see ops/sync.py)
"""
For small utility functions, one-line docstring is enough. For short internal helpers, no docstring required.