Oss Readiness

OSS Readiness — Public Release Gate

Audit a repository for open-source release basics. Scaffold missing public docs/templates. Generate AI-friendly docs (llms.txt, llms-full.txt). Validate CI. Sync version references.

Portability Rules

This skill must stay harness-agnostic and maintainer-agnostic:

• Accept natural-language prompts and slash-command shorthand as equivalent entry points.
• Keep AGENTS.md as the canonical agent-instructions file when one is scaffolded.
• Treat harness-specific files such as CLAUDE.md, .cursorrules, .windsurfrules, codex.md, or .opencode/config as optional aliases/mirrors — never the only supported path.
• Use placeholders in generated files. Never hardcode links, social handles, org names, or contact methods from this repository.
• Never invent maintainer contact channels. If the project does not provide one, leave a clear placeholder or omit the optional section.

Required Capabilities

| Capability | Used For | Required | Fallback | |---|---|---|---| | File read/write/edit | Audit and scaffold docs/templates | Yes | — | | Shell access | git/gh/grep/find-based checks | Recommended | Manual file inspection | | git | Repo metadata, tags, tracked-file checks | Recommended | Filesystem-only audit | | gh | GitHub metadata, PR/issue/security settings | Optional | Report as unchecked/manual | | node or python | Manifest/version extraction helpers | Optional | Grep/parse text manually |

The skill still works without shell tooling. Shell commands are accelerators, not requirements.

Entry Points

Use either natural language or shorthand. Route both to the same workflow.

| Intent | Example prompts | Route | |---|---|---| | Full audit | audit OSS readiness, /oss | references/checklist.md | | Scaffold missing files | scaffold missing OSS files, /oss fix | references/checklist.md | | Generate LLM docs | generate llms.txt, /oss llms | references/llms-generation.md | | Sync version refs | bump stale version refs in docs, /oss bump | references/version-sync.md | | Validate CI | check OSS CI readiness, /oss ci | references/ci-validation.md | | Review release title / notes / announcement framing | audit release messaging, is this a good OSS release title? | references/release-messaging.md |

Template Variables

Scaffolded files should use these placeholders until the target repo values are known:

| Placeholder | Meaning | |---|---| | {REPO_NAME} | Repository/project name | | {ORG} / {REPO} | Git hosting owner + repo slug | | {DESCRIPTION} | One-line project description | | {LICENSE_TYPE} | Chosen OSS license | | {PRIMARY_BRANCH} | Default branch name | | {PROJECT_REPO_URL} | Canonical source repository URL | | {PROJECT_HOMEPAGE} | Public project or docs homepage | | {COMMUNITY_SUPPORT_URL} | Support/discussion channel | | {SECURITY_REPORTING_URL} | Private vulnerability reporting channel | | {CODE_OF_CONDUCT_CONTACT} | Contact path for conduct reports | | {MAINTAINER_NAME} | Maintainer or org display name | | {MAINTAINER_URL} | Maintainer/org profile or homepage | | {MAINTAINER_CONTACT_URL} | Optional generic contact page/social/profile |

If a value is unknown, keep the placeholder or omit the optional block. Never substitute repo-specific defaults from this skill repository.

Stack Detection

Detect project type to customize audit logic:

# Package manager / language hints
IS_NPM=$(test -f package.json && echo true || echo false)
IS_CARGO=$(test -f Cargo.toml && echo true || echo false)
IS_PYTHON=$(test -f pyproject.toml -o -f setup.py && echo true || echo false)
IS_GO=$(test -f go.mod && echo true || echo false)

# Library/package vs app (heuristics)
# npm: package.json has "main" or "exports"
# cargo: Cargo.toml has [lib]
# python: pyproject has build metadata / published package info
# go: cmd/ often implies app; library repos may omit it

Checklist Summary (23 items)

BLOCKING (12) — must fix before public release

| # | Item | Severity | |---|---|---| | 1 | LICENSE file | BLOCKING | | 2 | README.md exists | BLOCKING | | 3 | README.md quality (H1, desc, install, usage, license) | BLOCKING | | 4 | CONTRIBUTING.md | BLOCKING | | 5 | .gitignore | BLOCKING | | 6 | No secrets in repo | BLOCKING | | 7 | CI: tests run | BLOCKING | | 8 | CI: lint runs | BLOCKING | | 9 | GitHub description set | BLOCKING | | 10 | CHANGELOG.md with version entry | BLOCKING | | 11 | llms.txt exists | BLOCKING | | 12 | llms-full.txt exists | BLOCKING |

WARN (11) — recommended

| # | Item | Severity | |---|---|---| | 13 | GitHub topics/tags | WARN | | 14 | AGENTS.md | WARN | | 15 | Harness-specific agent-instruction aliases | WARN | | 16 | SECURITY.md | WARN | | 17 | CODEOFCONDUCT.md | WARN | | 18 | Issue templates | WARN | | 19 | PR template | WARN | | 20 | CI: publish workflow (libraries) | WARN | | 21 | docs/ folder | WARN | | 22 | Version in docs matches package | WARN | | 23 | No TODO/FIXME in public src/ | WARN |

Full detection logic + fix actions → [references/checklist.md](references/checklist.md)

Scoring

SCORE = (blocking_pass / blocking_total) * 70 + (warn_pass / warn_total) * 30

A = score >= 90 AND 0 blocking failures
B = score >= 75 AND 0 blocking failures
C = score >= 60 (some blocking failures)
D = score >= 40
F = score < 40

Any blocking failure caps grade at C maximum.

Audit Output Format

═══════════════════════════════════════════════════════════════
 OSS READINESS — {org}/{repo}
 Version: {version} | Type: {npm|cargo|pip|go|app}
 Grade: {A-F} | Score: {0-100}
═══════════════════════════════════════════════════════════════

 BLOCKING
 ┌────────────────────────────────┬──────────┬───────────────────────┐
 │ Item                           │ Status   │ Note                  │
 ├────────────────────────────────┼──────────┼───────────────────────┤
 │ LICENSE                        │ PASS     │ MIT detected          │
 │ README.md                      │ WARN     │ Missing: usage, API   │
 │ llms.txt                       │ FAIL     │ Not found             │
 └────────────────────────────────┴──────────┴───────────────────────┘

 RECOMMENDED
 ┌────────────────────────────────┬──────────┬───────────────────────┐
 │ AGENTS.md                      │ FAIL     │ Not found             │
 │ Agent aliases                  │ WARN     │ AGENTS.md only        │
 └────────────────────────────────┴──────────┴───────────────────────┘

 BLOCKING failures: 2 — must fix before public release
 Warnings: 1 — recommended

 Run `scaffold missing OSS files` or `/oss fix` to scaffold missing files.
 Run `generate llms.txt` or `/oss llms` to create llms docs.
═══════════════════════════════════════════════════════════════

Scaffold Order

1. Detect stack (npm/cargo/python/go/app)
2. Run full checklist → identify missing items
3. Present: "Missing N BLOCKING + M WARN items. Scaffold all? [all / blocking only / pick]"
4. For each item:
   a. LICENSE → ask user for license type (MIT/Apache-2.0/ISC/GPL-3.0/BSD-3-Clause)
   b. README.md → scaffold from template placeholders
   c. CONTRIBUTING.md → fill template with repo + branch strategy
   d. SECURITY.md → fill template with repo + reporting channel placeholders
   e. CODE_OF_CONDUCT.md → fill Contributor Covenant template + conduct contact placeholder
   f. AGENTS.md → analyze repo, generate canonical instructions file
   g. Optional aliases → ask which harness aliases to create from AGENTS.md
   h. llms.txt + llms-full.txt → route to llms generation flow
   i. Issue templates → create .github/ISSUE_TEMPLATE/
   j. PR template → create .github/pull_request_template.md
   k. GitHub description/topics → update via `gh` when available
   l. CI workflows → generate starter workflow(s) based on stack
5. Report scaffolded files
6. Suggest re-running the audit before commit/push

Error Handling

| Error | Response | |---|---| | Not a git repo | "Not a git repository. OSS audit requires a repo." | | Private repo | Works but warns: "Repo is private. Audit shows readiness for going public." | | No package manager | Skip version-specific checks, note in output | | gh unavailable/auth missing | Continue filesystem checks; mark GitHub metadata as manual | | Maintainer contact unknown | Keep placeholder or omit optional contact block |

References

• [Checklist](references/checklist.md) — full detection + fix logic for all 23 items
• [LLMs Generation](references/llms-generation.md) — llms.txt + llms-full.txt algorithm
• [Version Sync](references/version-sync.md) — version detection + doc bumping
• [CI Validation](references/ci-validation.md) — CI pipeline rules + starter workflows
• [Release Messaging](references/release-messaging.md) — title, opening-summary, and announcement-quality rubric for public OSS releases

Templates

All scaffold templates live in templates/. Keep them generic and placeholder-driven.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bntvllnt
• Source: bntvllnt/agent-skills
• License: MIT
• Homepage: https://skills.sh/bntvllnt/agent-skills

Install and usage instructions live in the source repository linked above.