Publish an OSS Repo That Reads as Maintained
Type: Open-source — client-agnostic methodology, no project-specific detail.
Created by akbarsha — https://github.com/iamakbarsha1
Distilled from reworking a skills repository from merely functional to
publish-ready and finding that working code and green CI still read as
abandoned to GitHub's own UI and to a stranger browsing it.
Licence: Released under CC BY 4.0 — share and adapt for any purpose with
credit. Full text: LICENSE at the repository root.
Feedback & Support: If a rule here proves wrong or needs sharpening,
open an issue on the repository or contact the author at the profile link
above. If the problem is the agent not following a rule below rather than
the rule itself, that's an execution failure — acknowledge and correct it.
The core rule
"Has the files" is not "reads as maintained." A repo can have a LICENSE, a
changelog, and passing CI and still present as abandoned, because publishing
quality is signalled by machine-detectable facts — a canonical license the
platform's own detector recognizes, tagged releases per version, discoverable
topics, and CI that enforces the artifact's actual contract — and each of
those signals has to be verified through the platform's own API, not assumed
true because the file that's supposed to produce it exists.
Checks
- Fetch the canonical license text; never paraphrase it. GitHub's license
detector matches against the official legal text, not a legally-equivalent
summary — a hand-written paraphrase makes GitHub display the license as
"Other" and drops the repo out of license-filtered search. Pull the real
text from the canonical source (creativecommons.org, choosealicense.com,
the SPDX list) instead of transcribing it, and confirm detection through the
platform's own API rather than eyeballing the file. (A LICENSE file was a
hand-written CC BY 4.0 summary; GitHub showed the license as "Other" until
the canonical legal text replaced it, confirmed via
gh repo view --json licenseInfo — fetching the canonical text also sidestepped a content-filter
block that pasting the full 400-line legal text directly had tripped.)
- Cut a tag and a GitHub Release per version, not just a manifest bump. A
version bump that lives only in a manifest file is invisible outside the
diff — no
git tag output, no entry under Releases — and the repo reads as
abandoned even when the code is current. Every version bump gets a matching
git tag and release, not only the ones that feel significant. (A plugin
manifest had been bumped through several versions with zero git tags and
zero GitHub Releases behind them; the repo looked unmaintained until a tag
and release were cut for each version.)
- Set repo topics before anyone can find it by browsing. GitHub's topic
search and Explore surface only index repos with topics attached — zero
topics means zero discoverability outside an exact-name search. Add topics
for the domain, the language or framework, and the specific problem the
repo solves. (A skills repository had no GitHub topics set at all, so it
never surfaced in topic-based discovery until topics were added.)
- Make CI enforce the artifact's contract, not just its metadata. A
validator that checks frontmatter presence but not the body's required
shape lets a contribution merge with the right header and none of the
substance underneath — the gate exists but gates nothing that matters.
Enforce the structural contract itself (required sections, checklist
parity, grounding markers) so a shapeless PR fails CI before a human has to
catch it in review. (A skills-repo validator checked only that frontmatter
had
name and description; it never checked for the required ## The core rule section, checklist-to-check parity, or grounding markers, so a
skill missing all three would still have passed CI.)
Pre-flight check — before you call a repo publish-ready
If any box is unchecked, the repo has the files but doesn't read as
maintained — go close the gap before calling it publish-ready.
1---2name: publish-oss-repo3description: Use when preparing a repository for public release, or auditing one that already has working code but still reads as neglected to a stranger or to GitHub's own UI — "has the files" is not "reads as maintained". Triggers on "publish a repo", "open source this", "release", "make it look maintained", "license shows Other", "add topics", "GitHub release", "repo badges".4---56# Publish an OSS Repo That Reads as Maintained78**Type:** Open-source — client-agnostic methodology, no project-specific detail.910**Created by akbarsha — https://github.com/iamakbarsha1**1112Distilled from reworking a skills repository from merely functional to13publish-ready and finding that working code and green CI still read as14abandoned to GitHub's own UI and to a stranger browsing it.1516**Licence:** Released under CC BY 4.0 — share and adapt for any purpose with17credit. Full text: `LICENSE` at the repository root.1819**Feedback & Support:** If a rule here proves wrong or needs sharpening,20open an issue on the repository or contact the author at the profile link21above. If the problem is the agent not following a rule below rather than22the rule itself, that's an execution failure — acknowledge and correct it.2324## The core rule2526"Has the files" is not "reads as maintained." A repo can have a LICENSE, a27changelog, and passing CI and still present as abandoned, because publishing28quality is signalled by machine-detectable facts — a canonical license the29platform's own detector recognizes, tagged releases per version, discoverable30topics, and CI that enforces the artifact's actual contract — and each of31those signals has to be verified through the platform's own API, not assumed32true because the file that's supposed to produce it exists.3334## Checks3536- **Fetch the canonical license text; never paraphrase it.** GitHub's license37 detector matches against the official legal text, not a legally-equivalent38 summary — a hand-written paraphrase makes GitHub display the license as39 "Other" and drops the repo out of license-filtered search. Pull the real40 text from the canonical source (creativecommons.org, choosealicense.com,41 the SPDX list) instead of transcribing it, and confirm detection through the42 platform's own API rather than eyeballing the file. *(A LICENSE file was a43 hand-written CC BY 4.0 summary; GitHub showed the license as "Other" until44 the canonical legal text replaced it, confirmed via `gh repo view --json45 licenseInfo` — fetching the canonical text also sidestepped a content-filter46 block that pasting the full 400-line legal text directly had tripped.)*47- **Cut a tag and a GitHub Release per version, not just a manifest bump.** A48 version bump that lives only in a manifest file is invisible outside the49 diff — no `git tag` output, no entry under Releases — and the repo reads as50 abandoned even when the code is current. Every version bump gets a matching51 git tag and release, not only the ones that feel significant. *(A plugin52 manifest had been bumped through several versions with zero git tags and53 zero GitHub Releases behind them; the repo looked unmaintained until a tag54 and release were cut for each version.)*55- **Set repo topics before anyone can find it by browsing.** GitHub's topic56 search and Explore surface only index repos with topics attached — zero57 topics means zero discoverability outside an exact-name search. Add topics58 for the domain, the language or framework, and the specific problem the59 repo solves. *(A skills repository had no GitHub topics set at all, so it60 never surfaced in topic-based discovery until topics were added.)*61- **Make CI enforce the artifact's contract, not just its metadata.** A62 validator that checks frontmatter presence but not the body's required63 shape lets a contribution merge with the right header and none of the64 substance underneath — the gate exists but gates nothing that matters.65 Enforce the structural contract itself (required sections, checklist66 parity, grounding markers) so a shapeless PR fails CI before a human has to67 catch it in review. *(A skills-repo validator checked only that frontmatter68 had `name` and `description`; it never checked for the required `## The69 core rule` section, checklist-to-check parity, or grounding markers, so a70 skill missing all three would still have passed CI.)*7172## Pre-flight check — before you call a repo publish-ready7374- [ ] The LICENSE file is the canonical legal text from the official source,75 and the platform's own API (e.g. `gh repo view --json licenseInfo`)76 confirms the license is detected, not shown as "Other".77- [ ] Every version bump in the manifest or changelog has a matching git tag78 and a platform release, not just a diff.79- [ ] The repo has topics set for its domain, language/framework, and the80 specific problem it solves — not zero.81- [ ] CI enforces the artifact's structural contract (required sections,82 checklist parity, grounding markers), not just frontmatter presence.8384If any box is unchecked, the repo has the files but doesn't read as85maintained — go close the gap before calling it publish-ready.
iamakbarsha1