generating-readme
Use when generating, rewriting, or refreshing README.md for this loadout repository; when the Available loadouts catalog may be stale after loadout YAML changes; or when testing the loadout README generator against another cloned public repository. Triggers include README.md, loadout catalog, Available loadouts, and the docs/assets/loadout-banner.jpg banner.
- License 许可
- MIT
- 所属仓库
- sazlin/loadout
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- generating-readme
- description
- Use when generating, rewriting, or refreshing README.md for this loadout repository; when the Available loadouts catalog may be stale after loadout YAML changes; or when testing the loadout README generator against another cloned public repository. Triggers include README.md, loadout catalog, Available loadouts, and the docs/assets/loadout-banner.jpg banner.
02 资源文件 5
- 参考文档evals/evals.json2.2 KB
- 参考文档evals/files/tiny-readme.template.md216 B
- 参考文档references/readme-best-practices.md6.0 KB
- 脚本scripts/generate_readme.py8.8 KB
- 参考文档templates/README.md14.3 KB
03 SKILL.md 正文
Generating README
Repo-local skill for this loadout source tree. Do not add it to any loadout YAML. It is not consumer tooling.
Core principle: Prose follows references/readme-best-practices.md. The loadout catalog is generated. Hand-editing generated rows is a bug.
When to use
- Creating or refreshing this repo's
README.md - A loadout YAML was added, removed, renamed, or its artifacts changed
- User asks to generate a README with this skill (including a test clone)
Skip: Unrelated docs and changelogs. Do not vendor this
skill into skills/ or attach it to loadouts/*.yaml.
Workflow (this loadout repo)
- Read references/readme-best-practices.md.
- Start from templates/README.md. Keep the banner
docs/assets/loadout-banner.jpgand existing pitch / quick start unless a fact changed. - Run the generator script (fills or drops generated sections). It also
replaces
{{VERSION}}/{{VERSION_NUMBER}}with the newest git tag. Do not put{{VERSION}}on uvx git URLs; those stay@main. Edit pins in the template then regenerate; do not hand-edit README.md uvx lines.
uv run python .claude/skills/generating-readme/scripts/generate_readme.py \
--repo-root . \
--template .claude/skills/generating-readme/templates/README.md \
--output README.md
- After the script, only edit non-generated prose (gist, warnings,
local-dev commands). Do not edit between
<!-- generated:loadouts-catalog:start -->and<!-- generated:loadouts-catalog:end -->. That block starts with### Loadout files, a list of names linked toloadouts/<name>.yaml, then the catalog table. - Run
uv run pytest tests/test_readme_loadouts.py tests/test_generating_readme.py.
Other public repos (skill test)
The loadout template is not a generic README skeleton. Do not start a
foreign clone from templates/README.md.
- Inventory the clone: existing
README.md, license, package manifest, screenshots/gifs/svg demos, install/packager docs, benchmarks, man/-houtput, troubleshooting, contributing. If a visual exists, it stays. - If
README.mdalready exists, start from that file. Check it against the best-practices spine (visual, why, install that works on a clean machine, usage with sample output, caveats, contributing, license). Fill gaps. Do not flatten a README that is already the user manual (demo + install matrix + evidence + footguns). Fold long packager lists into<details>only if you must shorten; never delete them. - If there is no README, write one from the best-practices spine using only facts in the clone. Not the loadout template.
- You may still run
generate_readme.pywith--repo-rooton the clone only to inspect/strip generated blocks in a copy. Never pass--template templates/README.md --output <clone>/README.md— that overwrites a foreign README with loadout identity. Noloadouts/*.yaml→ catalog section stripped. Nodocs/assets/loadout-banner.jpg→ beaver banner stripped. Do not leave loadout-only sections (The Gist,uvx loadout init/sync, Agents, Manifest cheatsheet, Superpowers warning,LOADOUT_PATH). - Skip
tests/test_readme_loadouts.pyon a foreign clone.
Banner
This repository: keep the marked banner block. The script keeps it when
docs/assets/loadout-banner.jpg exists.
Foreign clone: the script drops that block when the image file is absent.
Never copy loadout-banner.jpg into another repo. Keep that project's
demo/logo if it has one (doc/screencast.svg, logo.svg, etc.).
Common mistakes
| Mistake | Fix |
|---|---|
| Hand-writing the loadout table | Run generate_readme.py |
| Mixing CLI tools into Hooks (or a leftover Etc. column) | Hooks lists only hooks; CLI Tools lists only cli_tools names |
Adding this skill to loadouts/*.yaml |
Leave it repo-local under .claude/skills/ |
| Inventing loadouts or install commands | Only YAML, tests, and commands you ran |
| ToC or 15 badges above the pitch | Title → few badges → one sentence |
| Copying this banner into another repo | Script strips it when the image file is missing |
| Flattening a CLI README that is the manual | Keep demo, install matrix, evidence, footguns |
| Starting a foreign README from the loadout template | Start from that repo's README or the spine, never this template |
Absolute blob/main links to own files |
Relative paths |
Additional resources
04 同仓库更多 Skills
demo
Demo skill
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
verification-before-completion
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
using-superpowers
Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
using-git-worktrees
Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback