Oss Docs
Audit or scaffold standard OSS files (CONTRIBUTING, CHANGELOG, AGENTS.md) before you open-source or share a repo with agents.
Overview
oss-docs is an agent skill most often used in Build (also Validate scope, Ship launch) that audits, scaffolds, and validates standard open-source documentation files in your repo.
Install
npx skills add https://github.com/boshu2/agentops --skill oss-docsWhat is this skill?
- Five commands: audit, scaffold (all or one file), update, and validate against OSS best practices
- Phase 0 auto-detects project type from go.mod, pyproject.toml, package.json, and Cargo.toml
- Output contract: CONTRIBUTING.md, CHANGELOG.md, and AGENTS.md
- Pragmatic Programmer and code-complete practices baked into generated content
- Requires git; MIT-licensed AgentOps skill with Read, Write, Edit, Glob, Grep, and Bash
- 5 documentation commands: audit, scaffold, update, validate
- 3-file output contract: CONTRIBUTING.md, CHANGELOG.md, AGENTS.md
Adoption & trust: 600 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your repo is almost ready to share but CONTRIBUTING, CHANGELOG, or AGENTS guidance is missing, outdated, or inconsistent with how you actually build and test.
Who is it for?
Indie maintainers open-sourcing a side project or tightening docs before the first external PR or agent session.
Skip if: Teams that only need API reference generation from source code with no OSS contributor workflow.
When should I use this skill?
Preparing a repository for open source release or when standard OSS documentation files are missing or stale.
What do I get? / Deliverables
You get a completeness audit plus scaffolded or updated CONTRIBUTING.md, CHANGELOG.md, and AGENTS.md tailored to detected project type, ready for contributors and coding agents.
- CONTRIBUTING.md
- CHANGELOG.md
- AGENTS.md
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Documentation is canonically shelved under Build because the skill writes and validates repo-local markdown artifacts, even though release prep also touches Ship. The docs subphase matches scaffold, audit, update, and validate commands that target CONTRIBUTING, CHANGELOG, and AGENTS.md rather than runtime code.
Where it fits
Run audit before deciding the repo is ready to flip public and accept outside contributors.
Scaffold AGENTS.md so Claude Code picks up test and style commands consistently.
Validate CONTRIBUTING and CHANGELOG exist and match release checklist before tagging v1.0.
How it compares
Structured OSS doc checklist and scaffolder, not a live documentation hosting or MkDocs site generator.
Common Questions / FAQ
Who is oss-docs for?
Solo and indie builders who want standard open-source documentation and agent-oriented AGENTS.md without writing every file from scratch.
When should I use oss-docs?
Use it in Validate when scoping an OSS release, in Build when standardizing repo docs, or in Ship launch prep when you need CONTRIBUTING and CHANGELOG before publishing.
Is oss-docs safe to install?
It can read and write repo files and run shell detection commands; review the Security Audits panel on this page and inspect allowed-tools before enabling Bash in sensitive repos.
SKILL.md
READMESKILL.md - Oss Docs
# OSS Documentation Skill Scaffold and audit documentation for open source projects. ## Overview This skill helps prepare repositories for open source release by: 1. Auditing existing documentation completeness 2. Scaffolding missing standard files 3. Generating content tailored to project type ## Commands | Command | Action | |---------|--------| | `audit` | Check which OSS docs exist/missing | | `scaffold` | Create all missing standard files | | `scaffold [file]` | Create specific file | | `update` | Refresh existing docs with latest patterns | | `validate` | Check docs follow best practices | --- ## Phase 0: Project Detection ```bash # Determine project type and language PROJECT_NAME=$(basename $(pwd)) LANGUAGES=() [[ -f go.mod ]] && LANGUAGES+=("go") [[ -f pyproject.toml ]] || [[ -f setup.py ]] && LANGUAGES+=("python") [[ -f package.json ]] && LANGUAGES+=("javascript") [[ -f Cargo.toml ]] && LANGUAGES+=("rust") # Detect project category if [[ -f Dockerfile ]] && [[ -d cmd ]]; then PROJECT_TYPE="cli" elif [[ -d config/crd ]]; then PROJECT_TYPE="operator" elif [[ -f Chart.yaml ]]; then PROJECT_TYPE="helm" else PROJECT_TYPE="library" fi ``` --- ## Subcommand: audit ### Required Files (Tier 1 - Core) | File | Purpose | |------|---------| | `LICENSE` | Legal terms | | `README.md` | Project overview | | `CONTRIBUTING.md` | How to contribute | | `CODE_OF_CONDUCT.md` | Community standards | ### Recommended Files (Tier 2 - Standard) | File | Purpose | |------|---------| | `SECURITY.md` | Vulnerability reporting | | `CHANGELOG.md` | Version history | | `AGENTS.md` | AI assistant context | | `.github/ISSUE_TEMPLATE/` | Issue templates | | `.github/PULL_REQUEST_TEMPLATE.md` | PR template | ### Optional Files (Tier 3 - Enhanced) | File | When Needed | |------|-------------| | `docs/QUICKSTART.md` | Complex setup | | `docs/ARCHITECTURE.md` | Non-trivial codebase | | `docs/CLI_REFERENCE.md` | CLI tools | | `docs/CONFIG.md` | Configurable software | | `examples/` | Complex workflows | --- ## Subcommand: scaffold ### Template Selection | Project Type | Focus | |--------------|-------| | `cli` | Installation, commands, examples | | `operator` | K8s CRDs, RBAC, deployment | | `service` | API, configuration, deployment | | `library` | API reference, examples | | `helm` | Values, dependencies, upgrading | --- ## Documentation Organization ``` project/ ├── README.md # Overview + quick start ├── AGENTS.md # AI assistant context ├── CONTRIBUTING.md # Contributor guide ├── CHANGELOG.md # Keep a Changelog format ├── docs/ │ ├── QUICKSTART.md # Detailed getting started │ ├── CLI_REFERENCE.md # Complete command reference │ ├── ARCHITECTURE.md # System design │ └── CONFIG.md # Configuration options └── examples/ └── README.md # Examples index ``` --- ## AGENTS.md Pattern ```markdown # Agent Instructions This project uses **<tool>** for <purpose>. Run `<onboard-cmd>` to get started. ## Quick Reference ```bash <cmd1> # Do thing 1 <cmd2> # Do thing 2 ``` ## Landing the Plane (Session Completion) **MANDATORY WORKFLOW:** 1. **Run quality gates** - Tests, linters, builds 2. **Commit changes** - Meaningful commit message 3. **PUSH TO REMOTE** - This is MANDATORY 4. **Verify** - All changes committed AND pushed ``` --- ## Style Guidelines 1. **Be direct**