repo-docs
Skill3 starsChanged 24 days agoMITView on GitHub
Create or upgrade README (banner or logo, badges), CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, LICENSE (MIT, Apache-2.0, any SPDX id, or proprietary), and TERMS, with docs/i18n/ translations and the .github/settings.yml About record. Use for "write a README", "add a license", "add a code of conduct / security policy / contributing guide", "translate the README", or "add badges". Every write is gated; never commits.
- Deletes or force-pushes
17 other projects use a version of this.
Adopted by
Most recently taken up by
- RMATI-11861/Claude-Skillstheir own version, first seen Nov 16, 2026
- teacupuk/tpstacktheir own version, first seen Nov 8, 2026
- korya/swd-skillstheir own version, first seen Nov 1, 2026
- certinia/debug-log-analyzer-mcptheir own version, first seen Oct 28, 2026
- ndthanhdev/aiotheir own version, first seen Oct 25, 2026
- bsene/skillstheir own version, first seen Oct 25, 2026
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- YurunChen/repo-docs-skills★ 457same name
- certinia/debug-log-analyzer-mcp★ 36same name
- IndelibleVivi/repo-docs-curator★ 10same name
- phanghonghao/THU-Awesome-Skills★ 8same name
- vbonk/repo-template★ 8same name
- bsene/skills★ 7same name
- OneDro1d/dark-factory★ 4same name
- korya/swd-skills★ 2same name
- IsthisLee/agent-context-manager★ 1same name
- IsthisLee/agentic★ 1same name
7 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- git-branch-createSkill
- git-branch-deleteSkill
- git-commitSkill
- git-fetchSkill
- git-mergeSkill
- git-pullSkill
- git-pushSkill
- git-tagSkill
- hf-downloadSkill
- hf-setupSkill
- hf-uploadSkill
- py-env-setupSkill
- repo-initSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. 0 are common, 7 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 15
Only the About panel text changes: edit .github/settings.yml directly, then apply it on GitHub by hand.
- Very specific: line 25
Probe, read-only: Run the probe below as written, under sh, so a glob that matches nothing is safe in zsh too.
- Distinctive: line 73
Write the English files and the settings record, and move into place each fetched text the plan lists (only those).
- Distinctive: line 74
Create the header images (below).
- Very specific: line 75
Delete the files the plan lists for deletion, and only those.
- Very specific: line 77
Pixel text: run the command; add --animate to both script calls for the animated option.
- Very specific: line 91
NEVER invent facts: features, numbers, commands, URLs, contacts, response times, or badges for services the probe did not find.
- Distinctive: line 92
NEVER write a license or code-of-conduct text from memory.
- Distinctive: line 93
NEVER publish an email address, a personal name, or another contact the user did not give for that purpose.
- Distinctive: line 94
NEVER change another party's copyright line without an explicit in-turn opt-in.
- Distinctive: line 95
NEVER drop content from an existing document without listing it in the step-9 plan, never delete or move a file the plan did not list, and …
- Very specific: line 96
NEVER write in the repository outside the in-scope documents, their translations in docs/i18n/, NOTICE and COPYING (when …
- Distinctive: line 97
NEVER upload images to external hosts.
- Very specific: line 98
NEVER commit, branch, or push.
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Goal
Leave the repository with the documents GitHub shows as tabs on its home page (README, Code of conduct, Contributing, License, Security), each following the standard in references/: a README a reader grasps in one screen, legal texts taken verbatim from their canonical sources, and community files that name real contacts. Existing documents keep every fact they hold; only their shape changes. The settings record .github/settings.yml holds the About panel values (description, website, topics) drafted with the README, so they stay in step with it.
When NOT to use
- A one-line fix in an otherwise fine document (a typo, a changed command): edit it directly, then update the same line in each translation.
- Only the About panel text changes: edit
.github/settings.ymldirectly, then apply it on GitHub by hand. - A documentation site, CHANGELOG, issue templates, or a privacy policy: out of scope; name the gap and stop.
- Choosing a license for a legal or commercial situation: this skill writes the file the user picks; it gives no legal advice.
Procedure
Terms such as choice question, independent reads, invoke, and suggest follow AGENTS.md (Skill authoring); in a non-interactive session every gate ends this skill.
Run every command in this skill in a POSIX shell. Repository paths are relative to the toplevel; each command recomputes ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" and runs from there, because shell state may not persist between commands. <skill-dir> is the skill directory (AGENTS.md, Skill authoring): this skill's references/ and scripts/ resolve against it, never against the repository (a repository may have its own unrelated references/); quote it in commands. $D is this run's scratch directory outside the repository, D="${TMPDIR:-/tmp}/repo-docs-$(printf %s "$ROOT" | cksum | cut -d' ' -f1)"; every command that removes something under it writes "${D:?}", so an unset D stops the command instead of reaching another path. Step 8 empties it, and step 12 removes it, except after a step-11 failure, when it keeps the saved originals. Read each reference file at the step that names it: layout.md, badges.md, logo.md, licenses.md, community.md; read rationale.md when the user asks why the skill works this way.
- Probe, read-only. Run the probe below as written, under
sh, so a glob that matches nothing is safe in zsh too; then read theProjectandCommandssections ofAGENTS.md.
Parse the repository path from the origin URL in any form (sh <<'EOF' ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; cd "$ROOT" || exit 1 echo "== documents (root, .github/, docs/, docs/i18n/)" for d in . .github docs docs/i18n; do ls -a "$d" 2>/dev/null | grep -iE '^(readme|contributing|code_of_conduct|security|license|licence|copying|terms|notice)' | sed "s|^|$d/|"; done echo "== header images"; ls .github/assets 2>/dev/null echo "== settings record"; ls .github/settings.yml 2>/dev/null echo "== template residue" grep -lE 'general-repo-template|General Repository Template' README* CONTRIBUTING* CODE_OF_CONDUCT* SECURITY* .github/*.md docs/*.md docs/i18n/*.md .github/assets/* .github/settings.yml 2>/dev/null echo "== copyright lines"; for f in LICENSE* LICENCE* COPYING* NOTICE*; do [ -f "$f" ] || continue; echo "-- $f"; grep -iE -m 3 '^[[:space:]]*copyright[[:space:]]' "$f"; done echo "== origin"; git remote get-url origin 2>/dev/null echo "== user.name"; git config user.name echo "== ci"; ls .github/workflows 2>/dev/null; ls .gitlab-ci.yml 2>/dev/null echo "== ecosystem" for f in pyproject.toml setup.py environment.yml requirements.txt .python-version package.json Cargo.toml go.mod pom.xml build.gradle build.gradle.kts CMakeLists.txt Dockerfile codecov.yml .codecov.yml .pre-commit-config.yaml mkdocs.yml .readthedocs.yaml *.csproj; do [ -e "$f" ] && echo "$f"; done echo "== tags"; git tag --list 'v*' --sort=-v:refname 2>/dev/null | head -n 3 true EOFhttps://host/<path>.git,git@host:<path>.git,ssh://git@host/<path>), dropping a trailing.git: on GitHub it is<owner>/<repo>; on GitLab it may hold subgroups (group/sub/repo), and the last segment is<repo>. When the host is GitHub, check visibility withcurl -s -o /dev/null -w '%{http_code}\n' https://api.github.com/repos/<owner>/<repo>: 200 means public (dynamic badges and Star History are available); 404 means private or absent (static badges, no Star History); any other result (rate limit, redirect, no network) is unknown, so ask the user. Report a short summary. - Pick the scope with two multi-select choice questions asked together, preselecting what is missing or is template residue: "documents": README, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY; "legal": LICENSE, TERMS (hosted services only). Nothing selected ends the skill.
- Template residue. A file the probe lists under "template residue", in a repository that is not the template itself (when unsure, ask). When any residue exists, the repository is a template copy, and its LICENSE is also residue unless the user says the copyright line shown by the probe is theirs; show that line in the question (when the probe found none, as with an Apache-2.0 text whose holder is in
NOTICEor nowhere, say so and ask who holds it). The translations of a residue file are residue too, whether or not the probe matched them, and so are.github/assets/files the probe matched. - Settings record.
.github/settings.ymlis in scope whenever README is, since its description mirrors the README tagline; it takes a mode like any other file, and the user may drop it from the step-9 plan. It is GitHub-specific: when the origin is on another forge, it is out of scope and a residue copy is listed for deletion. - Location. GitHub reads these files from
.github/, the root, thendocs/, in that order. A document that already lives in.github/ordocs/is upgraded where it is, unless the user agrees to move it to the root (a planned move); never create a root copy that another location would shadow or duplicate. Links to a document point at its actual location. - Modes. For each selected file, state one: create (absent, or residue), upgrade (a project version exists; reshape it and keep every fact), or sync (up to date; only translations or switchers change).
- Non-English originals. When an existing README or CONTRIBUTING is not in English, ask its locale (for example
zh-CNorzh-TW; nothing detects it reliably), then ask keep original (move it todocs/i18n/<NAME>.<locale>.mdas that language's translation, links rewritten perreferences/layout.md, and draft the English original from it) or retranslate (draft the English original from it, then translate that; the original is replaced). Translations found elsewhere (for example a rootREADME.<locale>.md) are planned moves todocs/i18n/with links rewritten; each such file is kept, unless the user asks for a fresh translation. When two planned moves, or a move and an existing file, target the same path, ask which to keep; the other is listed for deletion.
- Template residue. A file the probe lists under "template residue", in a repository that is not the template itself (when unsure, ask). When any residue exists, the repository is a template copy, and its LICENSE is also residue unless the user says the copyright line shown by the probe is theirs; show that line in the question (when the probe found none, as with an Apache-2.0 text whose holder is in
- Gather the facts. Read
references/layout.md, andreferences/community.mdwhen CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, or TERMS is in scope. Collect the project name, a one-line tagline, a two to four sentence intro, three to five highlights, setup and test commands, docs links, resource links, and (settings record in scope) its topics and website from the existing files,AGENTS.md, the manifests, and the conversation. Ask for what is still missing in one free-text message. Ask for the two contacts fromreferences/community.mdin the same message when CONTRIBUTING, CODE_OF_CONDUCT, or SECURITY is in scope, or right after step 4 when LICENSE is in scope (a proprietary choice there may drop some of those files). Anything still unknown stays a visible<placeholder>. - License (when in scope). Read
references/licenses.md, then ask with a choice question: MIT, Apache-2.0, Proprietary, other license (a typed SPDX id, for exampleGPL-3.0-or-later,BSD-3-Clause,MPL-2.0); give each option's one-line tradeoff and mark none recommended. Settle the holder and year perreferences/licenses.md(a residue LICENSE takes the user's holder; an existing project license keeps its holder unless the user opts in to a change). For Apache-2.0, also ask add NOTICE / skip. For Proprietary, ask whether CONTRIBUTING and CODE_OF_CONDUCT stay in scope. Replacing a license that is not residue needs the explicit in-turn opt-in described inreferences/licenses.md. - Header image (README in scope). Read
references/logo.md, then ask with a choice question: static pixel text (recommended when no logo exists), animated pixel text, logo prompt, custom or none. When a logo that is not residue already exists, offer keep current first and fold logo prompt into the free-text answer; residue banners count as no logo. For pixel text, settle the text (default: the repository name) and the palette. The text must hold at least one letter or digit and nothing but letters, digits, space, and. - _ / : ! ?; check it now and ask again when it does not. - Badges (README in scope). Read
references/badges.mdand build the recommended set in the order it gives (License first), capped at about eight. In upgrade mode start from the README's existing badges: keep them, fix any that are wrong or point at a missing service, and add catalog badges the evidence supports. Render it with the reserved list, then ask with a choice question: recommended (found set shown, the rest reserved in an HTML comment), minimal (license plus at most two others), custom (the user names badges to add or drop). - Languages (README or CONTRIBUTING in scope). English files are canonical. Ask with a multi-select choice question which translations to keep or add: Simplified Chinese (zh-CN) (recommended; preselect it on a first run), Traditional Chinese (zh-TW), Japanese (ja); the user may type other locales. Existing translations are kept unless the user drops them. The chosen set applies to both README and CONTRIBUTING.
- Fetch canonical texts. First run
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; D="${TMPDIR:-/tmp}/repo-docs-$(printf %s "$ROOT" | cksum | cut -d' ' -f1)"; rm -rf "${D:?}" && mkdir -p "$D", so no file from an earlier run survives. Then download the license text (andCOPYINGwhenreferences/licenses.mdcalls for it) and the Code of Conduct into$Dwith the commands inreferences/licenses.mdandreferences/community.md. A failed, empty, or unchecked download stops that file: report it, and never substitute a remembered text. When a later edit changes the license, re-run only the license fetch command (never this step's reset, which would delete the other texts), and remove aCOPYINGthe new license no longer needs withrm -f "${D:?}/COPYING"; a changed conduct contact needs only a new fill, not a new fetch. Nothing in the repository changes here. - Draft the English files. Draft every in-scope English file per the references. In create mode render each file in full (for fetched texts, render the filled lines and the source URL instead of the whole body); in upgrade mode render the diff plus every section, link, or image that moved or was removed, with the reason. Also render the plan, which step 11 follows exactly: every planned move with its link rewrites (a link whose target also moves in this plan points at the target's new path), every file written (English files, the settings record, translations, header images, fetched texts), and every file to delete (residue or dropped files that nothing in this run writes again). Then ask with a choice question: approve / edit (take changes, re-render, ask again) / abort (nothing written). Nothing is written yet.
- Draft the translations. For each chosen locale, translate the approved
README.mdandCONTRIBUTING.md(when in scope) per the translation rules inreferences/layout.md, skipping a translation the step-2 keep original or kept-file answer covers. When the set of languages changed, also render the updated switcher line of every existing file. Render each file in full, then ask write all / edit / abort (nothing written). With no translation work, ask write all / abort over the step-9 plan instead. - Write. On write all, follow the plan in this order, so no write lands on a file before that file has been moved or saved:
- Copy every file the plan moves, replaces, or deletes into
$D/orig/, keeping its relative path. - Make the planned moves from those copies, rewriting links as planned, and remove each source path.
- Write the English files and the settings record, and move into place each fetched text the plan lists (only those); then write the translations and switcher changes.
- Create the header images (below).
- Delete the files the plan lists for deletion, and only those; never delete a path this run has written.
On any failure, stop, keep
$D, and report what was written, moved, and deleted, with the path of$D/orig/; then ask restore originals (copy them back over the partial result) / keep as is. In a non-interactive session, report and leave$Din place.
- Pixel text: run the command; add
--animateto both script calls for the animated option.ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; cd "$ROOT" && mkdir -p .github/assets && sh "<skill-dir>/scripts/pixel-banner.sh" --text "<text>" --out .github/assets/banner-light.svg --from "<light-from>" --to "<light-to>" && sh "<skill-dir>/scripts/pixel-banner.sh" --text "<text>" --out .github/assets/banner-dark.svg --from "<dark-from>" --to "<dark-to>" - Logo prompt: fill the prompt template in
references/logo.mdand give it to the user in a fenced block. The logo block inREADME.mdstays in an HTML comment until the file exists; tell the user the exact path and to uncomment it (or re-run this skill). - Custom: copy a local file into
.github/assets/under the name the README uses; link a URL directly. - Keep current and none: nothing to do.
- Copy every file the plan moves, replaces, or deletes into
- Report. List the files written, moved, and deleted, each file's mode, the license, the badges shown and reserved, and every placeholder left (logo file, missing facts). On GitHub, when
SECURITY.mdpoints at private vulnerability reporting, remind the owner to enable it (Settings, Security). When the settings record was written, remind the owner that GitHub does not read it: compare the About panel with the file first, so a value set only on the web is not lost, then apply it by hand (the gear icon next to About, and Settings, General for the template flag) unless the Settings App is installed; when GitHub refuses or rewrites a topic, copy the accepted topics back into the file. Unless step 11 failed, remove the scratch directory:ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; D="${TMPDIR:-/tmp}/repo-docs-$(printf %s "$ROOT" | cksum | cut -d' ' -f1)"; rm -rf "${D:?}". When another skill invoked this one, return to it and leave the commit to it; otherwise suggestgit-commit, since these documents belong in one commit.
Hard rules
- NEVER invent facts: features, numbers, commands, URLs, contacts, response times, or badges for services the probe did not find. Unknowns stay visible
<placeholder>text or reserved comments. - NEVER write a license or code-of-conduct text from memory; fetch it or stop.
- NEVER publish an email address, a personal name, or another contact the user did not give for that purpose; a residue copyright line is replaced, never carried into a consumer's files.
- NEVER change another party's copyright line without an explicit in-turn opt-in.
- NEVER drop content from an existing document without listing it in the step-9 plan, never delete or move a file the plan did not list, and never delete anything before every write has succeeded.
- NEVER write in the repository outside the in-scope documents, their translations in
docs/i18n/,NOTICEandCOPYING(whenreferences/licenses.mdcalls for them),.github/assets/, and.github/settings.yml; downloads and saved originals stay in$D. - NEVER upload images to external hosts; header images live in the repository or come from a URL the user gave.
- NEVER commit, branch, or push; suggest
git-commit, or leave it to the invoking skill. - README and CONTRIBUTING files and their translations may use non-English text, and README files may use emoji; every other file this skill writes stays ASCII.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

