Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.
.claude/skills/davila7-crafting-effective-readmes/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-03 | ✗→✓ | ▲ Improved | -35% | 0% |
| case-06 | ✗→✓ | ▲ Improved | -5% | 0% |
| case-19 | ✗→✓ | ▲ Improved | -7% | 0% |
| case-20 | ✓→✓ | ＝ Same ✓ | 12% | 0% |
| case-07 | ✓→✓ | ＝ Same ✓ | -12% | 0% |
READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder.
Always ask: Who will read this, and what do they need to know?
Ask: "What README task are you working on?"
| Task | When | |------|------| | Creating | New project, no README yet | | Adding | Need to document something new | | Updating | Capabilities changed, content is stale | | Reviewing | Checking if README is still accurate |
Creating initial README:
Adding a section:
Updating existing content:
Reviewing/refreshing:
After drafting, ask: "Anything else to highlight or include that I might have missed?"
| Type | Audience | Key Sections | Template | |------|----------|--------------|----------| | Open Source | Contributors, users worldwide | Install, Usage, Contributing, License | templates/oss.md | | Personal | Future you, portfolio viewers | What it does, Tech stack, Learnings | templates/personal.md | | Internal | Teammates, new hires | Setup, Architecture, Runbooks | templates/internal.md | | Config | Future you (confused) | What's here, Why, How to extend, Gotchas | templates/xdg-config.md |
Ask the user if unclear. Don't assume OSS defaults for everything.
Every README needs at minimum:
section-checklist.md - Which sections to include by project typestyle-guide.md - Common README mistakes and prose guidanceusing-references.md - Guide to deeper reference materials| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-01 | fail→fail | 15,252 | 9,064 | -41% | 1 | 1 | 0% | 2,735 | 2,012 | -26% | 0 | 0 | — |
case-02 | fail→fail | 14,023 | 9,691 | -31% | 1 | 1 | 0% | 2,327 | 2,216 | -5% | 0 | 0 | — |
case-03 | fail→pass | 14,914 | 5,895 | -60% | 1 | 1 | 0% | 2,439 | 1,596 | -35% | 0 | 0 | — |
case-04 | fail→fail | 14,523 | 9,831 | -32% | 1 | 1 | 0% | 2,743 | 2,506 | -9% | 0 | 0 | — |
case-05 | fail→fail | 10,288 | 3,995 | -61% | 1 | 1 | 0% | 1,764 | 1,175 | -33% | 0 | 0 | — |
case-20 | pass→pass | 11,588 | 8,825 | -24% | 1 | 1 | 0% | 2,492 | 2,781 | +12% | 0 | 0 | — |
case-06 | fail→pass | 12,713 | 8,109 | -36% | 1 | 1 | 0% | 2,063 | 1,959 | -5% | 0 | 0 | — |
case-07 | pass→pass | 7,540 | 3,630 | -52% | 1 | 1 | 0% | 1,351 | 1,193 | -12% | 0 | 0 | — |
case-08 | fail→fail | 13,006 | 8,312 | -36% | 1 | 1 | 0% | 2,279 | 2,115 | -7% | 0 | 0 | — |
case-09 | pass→pass | 13,576 | 6,319 | -53% | 1 | 1 | 0% | 2,311 | 1,785 | -23% | 0 | 0 | — |
case-15 | pass→pass | 10,455 | 6,558 | -37% | 1 | 1 | 0% | 1,953 | 1,840 | -6% | 0 | 0 | — |
case-10 | pass→pass | 14,204 | 7,349 | -48% | 1 | 1 | 0% | 2,385 | 2,029 | -15% | 0 | 0 | — |
case-11 | pass→pass | 12,795 | 6,384 | -50% | 1 | 1 | 0% | 2,303 | 1,812 | -21% | 0 | 0 | — |
case-12 | pass→pass | 8,893 | 4,144 | -53% | 1 | 1 | 0% | 1,607 | 1,379 | -14% | 0 | 0 | — |
case-13 | pass→pass | 7,268 | 3,569 | -51% | 1 | 1 | 0% | 1,382 | 1,330 | -4% | 0 | 0 | — |
case-14 | pass→pass | 6,587 | 1,485 | -77% | 1 | 1 | 0% | 1,188 | 909 | -23% | 0 | 0 | — |
case-16 | pass→pass | 6,814 | 4,509 | -34% | 1 | 1 | 0% | 1,272 | 1,495 | +18% | 0 | 0 | — |
case-17 | pass→pass | 7,067 | 2,882 | -59% | 1 | 1 | 0% | 1,149 | 1,138 | -1% | 0 | 0 | — |
case-18 | pass→pass | 8,547 | 4,174 | -51% | 1 | 1 | 0% | 1,584 | 1,417 | -11% | 0 | 0 | — |
case-19 | fail→pass | 14,410 | 7,428 | -48% | 1 | 1 | 0% | 2,052 | 1,915 | -7% | 0 | 0 | — |
case-21 | pass→pass | 13,487 | 7,576 | -44% | 1 | 1 | 0% | 2,714 | 2,001 | -26% | 0 | 0 | — |
case-22 | pass→pass | 5,087 | 5,159 | +1% | 1 | 1 | 0% | 1,132 | 1,619 | +43% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +14 percentage points is the difference between those two pass rates over the 22 comparable cases.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.