Repository Documentation Suite

Complete Docs Inventory

A well-documented public repository should have these files:

Platform note: The file paths below use GitHub conventions. For GitLab or Bitbucket repositories, load the platform-profiles skill for equivalent paths (e.g. .gitlab/issue_templates/ instead of .github/ISSUE_TEMPLATE/).

Tier 1: Essential (Every Public Repo)

Tier 2: Professional (Active Projects)

Tier 3: Mature (Established Projects)

Repository Metadata (Hosting Platform Settings)

Beyond files, a well-configured repo also needs correct platform-level metadata for discoverability. The commands below use gh CLI (GitHub). For GitLab, use glab. For Bitbucket, use the REST API. Load the platform-profiles skill for full CLI mapping.

Reading Current Metadata

gh repo view --json topics,homepageUrl,description

Setting Metadata

# Topics — add individually
gh repo edit --add-topic typescript --add-topic documentation --add-topic cli

# Description
gh repo edit --description "Generate repository documentation that sells as well as it informs."

# Website URL
gh repo edit --homepage "https://docs.example.com"

Topic Suggestion Framework

See SKILL-reference.md for the full topic category table and rules. Aim for 5-10 topics, lowercase and hyphenated.

See SKILL-reference.md for description guidance, website URL priorities, package registry configuration, social preview specs, and visual assets guidance.

Audit Workflow

Step 1: Scan Existing Docs

# Check for all expected files
for f in README.md LICENSE CONTRIBUTING.md CHANGELOG.md ROADMAP.md CODE_OF_CONDUCT.md SECURITY.md SUPPORT.md llms.txt AGENTS.md CLAUDE.md .cursorrules .windsurfrules .clinerules; do
  [ -f "$f" ] && echo "✓ $f" || echo "✗ $f (missing)"
done

# Check .github templates and AI context files
for f in .github/ISSUE_TEMPLATE/bug_report.yml .github/ISSUE_TEMPLATE/feature_request.yml .github/PULL_REQUEST_TEMPLATE.md .github/ISSUE_TEMPLATE/config.yml .github/copilot-instructions.md; do
  [ -f "$f" ] && echo "✓ $f" || echo "✗ $f (missing)"
done

# Check for common alternatives
[ -f ".github/ISSUE_TEMPLATE/bug_report.md" ] && echo "⚠ bug_report.md found (consider migrating to YAML forms)"

Step 2: Quality Check Existing Files

For each existing file, check:

• README.md: Does it pass the 4-question test? Does it have badges? Is the quickstart working?
• CONTRIBUTING.md: Does it match the actual development workflow?
• CHANGELOG.md: Is it up to date with the latest release?
• SECURITY.md: Does it include a responsible disclosure process?

License Validation

See SKILL-reference.md for the three licence validation checks (file exists, manifest matches, no verbatim text in context files).

Step 3: Generate Missing Files

Use the appropriate skill/template for each missing file. Generate in priority order:

1. README.md (if missing or needs overhaul)
2. CONTRIBUTING.md
3. Issue templates
4. PR template
5. CHANGELOG.md
6. Everything else

Templates

Templates for CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, issue templates, PR template, FUNDING.yml, SUPPORT.md, release.yml, and CITATION.cff are in the companion file SKILL-templates.md. Load it when generating specific files from the inventory.

Content filter note: Several templates trigger Claude Code's content filter. See SKILL-templates.md for per-file generation strategies (fetch vs chunked write).

LICENSE Selection Framework

See SKILL-reference.md for the licence comparison table and decision guidance. Default to MIT for most projects; use choosealicense.com or GitHub's built-in licence picker to generate the file.