Menu
Generate README files for projects in the df12 Productions house style
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Write and revise tutorials and how-to guides — the two practical, action-oriented kinds of documentation. Use this skill whenever the user asks to write, draft, structure, or fix a tutorial, a getting- started guide, a walkthrough, a lesson, a how-to, a task guide, a recipe, a procedure, or a troubleshooting guide. Also trigger when a document tries to both teach and get a job done at once, when a "tutorial" reads like a reference dump, when steps fail for readers, or when the user is unsure whether they need a tutorial or a how-to. The skill first classifies the document by user need (study versus work), then drives a test-the-path workflow: scope the journey or the goal, execute it end to end recording real output, draft to the right anatomy, edit out blurred boundaries, and hand off to reference and explanation. It is grounded in Diátaxis, Carroll's minimalism, Gagné's events of instruction, and cognitive load theory.
Groom and curate a *living* GIST (Goals, Ideas, Steps, Tasks) roadmap as it accretes work during execution — audit findings, code and design review follow-ups, dogfooding fixes, and new ideas. Use this skill whenever you are maintaining an existing roadmap rather than authoring one: when refactoring or re-architecting tasks have piled up and need consolidating into proper steps; when a hardening or refactoring phase has inflated into many single-task "steps"; when new feature ideas risk being buried among refactoring work, or refactoring work risks being dismissed as low value; when deciding what is genuine debt versus self-generating audit churn; or whenever a roadmap has grown and needs to be made legible again. This is the maintenance counterpart to the roadmap-doc skill, which authors a roadmap from design documents — read roadmap-doc for the GIST grammar, format, and anti-patterns this skill assumes.
Write and maintain a project's `CHANGELOG.md` following the Common Changelog style. Use this skill whenever the user asks to create, draft, update, rewrite, or review a changelog; add a release entry; record notable changes since the last tag; cut a release; promote a prerelease; or document a yanked release. Trigger on phrases such as "update the changelog", "add a changelog entry", "what changed since v1.2.0?", "draft release notes from git history", or "write CHANGELOG.md".
Create GitHub pull requests (PRs) with complete draft PR metadata, reviewer-focused descriptions, roadmap and issue references, execplan identification, and en-GB Oxford English. Use whenever Codex opens, drafts, revises, or prepares a pull request description or title for a branch.
Generate terms of reference documents that capture the problem space — domain, market, users, job-to-be-done, scope, constraints, and open questions — before any solution work begins. Use this skill whenever the user asks to write, draft, or produce a terms of reference, project charter, product brief, problem statement, vision and scope document, domain knowledge document, or "what is this for" document. Also trigger when the user starts a new project without an established brief, wants to capture domain knowledge from a subject-matter expert, needs to draw explicit scope boundaries before technical design, or asks to elicit and document the rationale for a system. The skill drives an elicitation-led workflow: prior-art discovery, gap analysis, structured interview, drafting, editing, and handoff to the design and roadmap skills. It produces documents in the style of df12 Productions — precise, evidence-grounded, and free of aspirational fluff.
Generate development roadmaps from design documents, RFCs, and ADRs found in a repository or provided with the prompt. Use this skill whenever the user asks to create, draft, write, or generate a roadmap, execution plan, delivery plan, or development plan for a software project — especially when design documents, RFCs, or ADRs are available as source material. Also trigger when the user asks to turn a design document or set of RFCs into actionable work items, or to plan the build order for a system described in technical documentation. Trigger even for partial requests such as "plan the next phase" or "break this design into tasks" when design documentation is present.
| name | df12-readme |
| description | Generate README files for projects in the df12 Productions house style |
Use this skill when creating or updating README.md files for df12 Productions
projects. This skill produces READMEs that are welcoming, clear, and get
developers to "Hello World" quickly.
df12 Productions: https://df12.studio/
/readme, /df12-readmeFollow this structure, adapting as needed for the project:
# Project Name
*Brief tagline explaining what this project does (one line).*
[Optional: short paragraph expanding on the tagline, 2-3 sentences max]
______________________________________________________________________
## Why {project-name}?
Explain the problem this solves and why someone would use it. Keep it brief
(3-5 bullet points or a short paragraph).
______________________________________________________________________
## Quick start
### Installation
[Minimal steps to install]
### Basic usage
[Minimal code example that demonstrates the core functionality]
______________________________________________________________________
## Features
[Brief feature list—bullet points work well here]
______________________________________________________________________
## Learn more
- [Users' Guide](docs/users-guide.md) — full documentation
- [Developers' Guide](docs/developers-guide.md) — contributing and development
- [Roadmap](docs/roadmap.md) — planned features and progress
______________________________________________________________________
## Licence
[Licence type] — see [LICENSE](LICENSE) for details.
______________________________________________________________________
## Contributing
[Brief invitation to contribute, link to contribution guidelines]
Rapid time to Hello World: Centre a working code example early. The reader should be able to copy-paste and see something work within the first scroll.
Link, don't duplicate: The README is a signpost, not an encyclopaedia.
Point to docs/users-guide.md for full documentation rather than
reproducing it.
Code examples should work: Every code block should be correct and
runnable. Use language identifiers (bash, rust, python, etc.).
Horizontal rules for major sections: Use ______ (six or more
underscores) between major sections for visual breathing room.
Sentence case headings: "Quick start" not "Quick Start".
The 80-column rule: Wrap prose at 80 columns for readability in terminals and diff views.
Before writing, gather information from these project locations:
| Information needed | Where to find it |
|---|---|
| Project purpose | docs/design-doc.md or principal design document |
| Features and scope | Design document, Cargo.toml/pyproject.toml |
| Installation | docs/users-guide.md, build configuration |
| Usage examples | docs/users-guide.md, examples/ directory |
| Current status | docs/roadmap.md |
| Licence | LICENSE file |
| Contributing info | AGENTS.md, docs/developers-guide.md |
Table 1: Information sources for README content.
If you cannot locate the principal design document, ask the user.
# {Project Name}
*{One-line description of what it does}.*
{Optional: 2-3 sentence expansion if the tagline needs context}
______________________________________________________________________
## Why {project-name}?
{Brief explanation of the problem and why this project exists.
Use bullet points for multiple value propositions:}
- **{Benefit 1}**: {explanation}
- **{Benefit 2}**: {explanation}
- **{Benefit 3}**: {explanation}
______________________________________________________________________
## Quick start
### Installation
```{language}
{minimal installation command(s)}
{minimal working example—aim for < 20 lines}
{Licence type} — see LICENSE for details.
Contributions welcome! Please see AGENTS.md for guidelines.
## Example excerpts from df12 projects
### Good title and tagline
```markdown
# 🫏 git-donkey
*For projects that require a worktree, git-donkey provides support.*
# rstest-bdd
*Where Rustaceans come for their gourd‑related puns.*
> **TL;DR**: Behaviour‑Driven Development (BDD), idiomatic to Rust. Keep your
> unit tests and your acceptance tests on the same vine, run everything with
> `cargo test`, and reuse your `rstest` fixtures.
## Why claude-q?
When working with Claude Code, you often think of tasks while in the
middle of something else:
- "I should refactor that module... but not now"
- "Need to add tests for this... after the current feature"
- "This would be a good time to update the docs"
Instead of interrupting your flow or forgetting these tasks, queue them
with `=qput` and let Claude handle them when the time is right.
## Quick start
```shell
# Create a worktree for feature/awesome-stuff from main
git donkey feature/awesome-stuff
# Track a remote branch
git track feature/from-teammate
## What to avoid
- **Walls of text**: Break up long explanations. If it needs that much detail,
it belongs in the Users' Guide.
- **Emoji overload**: One or two is friendly; a dozen screams "AI wrote this."
- **Vague descriptions**: "A tool for doing things" tells the reader nothing.
- **Missing code examples**: The Quick Start section must have runnable code.
- **Duplicating documentation**: Link to guides instead of copying them.
- **Broken examples**: Test that code blocks actually work.
- **US spellings**: Use British English except in code identifiers.
## Process
1. **Read the project**: Examine design documents, existing code, and any
existing documentation.
2. **Identify the core value**: What problem does this solve? Why would someone
use it?
3. **Find the simplest working example**: What's the shortest path to "it
works"?
4. **Draft the README**: Follow the structure above.
5. **Verify code examples**: Ensure they compile/run.
6. **Check links**: Ensure all documentation links are valid.
7. **Apply style guide**: British English, 80-column wrap, sentence case
headings.
## Validation checklist
Before finalising the README, verify:
- [ ] Title clearly identifies the project
- [ ] Tagline explains what it does in one line
- [ ] "Why" section explains the value proposition
- [ ] Quick start includes installation and a working example
- [ ] Code examples are correct and use language identifiers
- [ ] Links to Users' Guide, Developers' Guide, and Roadmap are present
- [ ] Licence section references the LICENSE file
- [ ] Contributing section invites contributions
- [ ] British English spelling throughout (except code identifiers)
- [ ] Paragraphs wrapped at 80 columns
- [ ] Headings in sentence case
- [ ] Emoji usage is minimal (0-2 total)