SuperAPI AI Directory

audit

General & other

View repository

Updated 10-16 08:41

About this skill

Repository Hygiene Audit

Essential Files Checklist

File Purpose Why It Matters
README.md Project overview, quick start First impression, onboarding
LICENSE Legal terms for use Without one, code is "all rights reserved" by default
.gitignore Files to exclude from git Prevents committing secrets, build artifacts
.env.example Template for env vars Shows structure without revealing secrets
CONTRIBUTING.md How to contribute Reduces friction for contributors
CHANGELOG.md Version history Users track what changed
CODE_OF_CONDUCT.md Community expectations Required for many registries

.gitignore Essentials

Minimum patterns for any repo:

# Secrets
.env
.env.local
.env.*.local

# OS
.DS_Store
Thumbs.db
desktop.ini

# Editors
.vscode/
.idea/
*.swp
*.swo
*~

# Logs
*.log
logs/

# Dependencies (language-specific)
node_modules/
__pycache__/
*.pyc
.venv/
venv/
target/
vendor/

# Build artifacts
dist/
build/
out/
*.egg-info/

# Coverage
coverage/
.coverage
htmlcov/

Language additions:

  • Node: node_modules/, dist/, .next/, .turbo/
  • Python: __pycache__/, *.pyc, .venv/, venv/, .pytest_cache/, .mypy_cache/
  • Rust: target/, Cargo.lock (for libs, commit for bins)
  • Go: vendor/, bin/
  • Terraform: .terraform/, *.tfstate*, *.tfvars (if contains secrets)
  • Java: target/, .gradle/, *.class

README Essentials

Minimum sections:

# Project Name

One-line tagline.

## Why
What problem does this solve?

## Install
Exact commands to install.

## Quick Start
Minimal working example.

## Usage
Common use cases with code examples.

## License
License name with link to LICENSE file.

Nice to have:

  • Badges (build status, version, license)
  • Screenshots/GIFs for visual tools
  • Link to docs site
  • Contributing section (even if just linking CONTRIBUTING.md)
  • Acknowledgments / credits

.env.example Pattern

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Auth
JWT_SECRET=change-me-to-a-long-random-string
OAUTH_CLIENT_ID=your-oauth-client-id
OAUTH_CLIENT_SECRET=your-oauth-client-secret

# External APIs
OPENAI_API_KEY=sk-...
AWS_REGION=us-east-1

# Feature flags
ENABLE_BETA_FEATURES=false

Rules:

  • Every variable the app reads at runtime
  • Placeholder values that look like the real thing (so users know the format)
  • Comments grouping related vars
  • Never real credentials

Secret Scanning

Before publishing a repo publicly, scan for leaked secrets:

# Check git history for common patterns
git log -p | grep -iE 'api[_-]?key|secret|password|token|bearer' | grep -v example

# Dedicated tools
gitleaks detect --source=. --verbose
trufflehog git file://. --only-verified

# GitHub's own scanner runs automatically on public repos

If secrets are found in history:

  1. Rotate them immediately
  2. Use git filter-repo or BFG to remove from history
  3. Force-push cleaned history
  4. Enable GitHub secret scanning for the repo going forward

LICENSE Choice

License When to Use
MIT Permissive, short, widely used. Best default for most projects
Apache 2.0 Like MIT but with patent protection. Larger projects, corporate use
GPL-3.0 Copyleft -- derivatives must also be GPL. Strong software freedom
BSD-3-Clause Very permissive, slightly different from MIT
Unlicense / CC0 Public domain, no restrictions
Proprietary Internal/commercial code. No file = "all rights reserved"

Generate: https://choosealicense.com

Config File Hygiene

  • Commit: package.json, requirements.txt, Dockerfile, tsconfig.json
  • Commit with placeholders: .env.example, config.example.yml
  • Do NOT commit: .env, config.yml (with real values), node_modules/, build artifacts
  • Lock files (package-lock.json, yarn.lock, Cargo.lock, poetry.lock): commit for apps, skip for libs

Auditing an Existing Repo

1. Check for .gitignore -- does it cover your stack?
2. Check for README -- is it accurate and useful?
3. Check for LICENSE -- is there one?
4. Check for .env.example -- if app uses env vars
5. Scan for committed secrets (gitleaks)
6. Check for outdated dependencies
7. Check CI status -- is it green?
8. Check stale branches -- prune or merge
9. Check for TODO/FIXME density -- tech debt signal
10. Check commit message quality -- conventional commits?

Anti-Patterns

Anti-Pattern Problem Do Instead
No README Users can't onboard Even a 5-line README helps
README listing what code does Duplicates the code Focus on WHY and HOW TO USE
No LICENSE "All rights reserved" by default -- users can't legally use it Pick one from choosealicense.com
Committing .env Secrets leaked forever Use .env.example, add .env to .gitignore
Broken links in README Unprofessional, frustrating Test links periodically
Outdated dependencies with CVEs Security risk Automated updates (Renovate, Dependabot)
Empty CONTRIBUTING.md Signals unmaintained Either write one or remove file