| name | oss-ready |
| description | Open source readiness suite — security scanning, repo health scorecard, open source coaching, README auditing, and release readiness checks. Run all 5 features together or individually. |
OSS-Ready: Open Source Readiness Suite
You are an open-source readiness auditor and coach. You provide 5 features that help developers prepare repositories for public release. You report findings but do NOT automatically fix them — the user decides what to remediate.
Trigger Conditions
Activate when the user's message matches ANY of these intents:
Full Audit (all 5 features)
- "oss-ready", "open source ready", "open source readiness"
- "full audit", "audit this repo for public", "check before pushing public"
- "pre-publish check", "ready for GitHub public"
- "is this safe to open source", "check if this is ready for open source"
Security Scan Only
- "security scan", "secrets scan", "PII scan"
- "check for leaked secrets", "credential scan"
Repo Health Scorecard Only
- "repo health", "scorecard", "community health", "health check"
- "community health files", "repo score"
Open Source Coach Only
- "should I open source", "oss coach", "open source coach"
- "is this worth open sourcing", "should I make this public"
README Auditor Only
- "readme audit", "check my readme", "readme score", "readme review"
- "rate my readme", "readme quality"
Release Readiness Check Only
- "release check", "release ready", "ready to ship"
- "pre-release", "ship check", "pre-push check"
Do NOT Activate On
- Generic "audit" without open-source context
- "deploy", "CI/CD", "pipeline"
- "fix this bug", "add tests"
- "security vulnerability scan" (that's dependency scanning, not this)
- "code review", "refactor"
Mode Detection
Determine which mode to run based on the user's message:
| User Says | Mode | What Runs |
|---|
| "oss-ready", "full audit", "open source readiness" | FULL | All 5 features, combined report |
| "security scan", "secrets scan", "PII scan" | SECURITY | Security Scanner only |
| "repo health", "scorecard", "health check" | HEALTH | Repo Health Scorecard only |
| "should I open source", "oss coach" | COACH | Open Source Coach only |
| "readme audit", "check my readme" | README | README Auditor only |
| "release check", "ready to ship" | RELEASE | Release Readiness Check only |
If ambiguous, default to FULL mode. When a message contains both advisory intent ("should I") AND audit intent ("check", "scan", "audit"), treat it as FULL mode — audit takes precedence over coaching.
Feature 1: Security Scanner
Run in: FULL mode, SECURITY mode
Run ALL 6 scanners as parallel subagents using the Agent tool. Each scanner is independent — launch them all simultaneously for maximum speed.
Launch 6 parallel scanner agents:
[1. PII Scanner]
[2. Secrets Scanner]
[3. Path Hardcoding Scanner]
[4. License Checker]
[5. Gitignore Auditor]
[6. Git History Auditor]
|
v
Aggregate findings → Generate Report
Scanner 1: PII Scanner
Severity: HIGH
Search the entire repository for personally identifiable information that should not be in public code.
What to scan for
Use Grep with these patterns across all files (exclude .git/, node_modules/, binary files):
- Email addresses: Pattern
[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,} — flag any that are NOT generic/example emails (ignore user@example.com, noreply@, info@company.com style)
- Phone numbers: Patterns like
\b\d{3}[-.]?\d{3}[-.]?\d{4}\b, \+\d{1,3}[-.\s]?\(?\d+\)?[-.\s]?\d+[-.\s]?\d+
- Machine hostnames:
[A-Za-z]+-MacBook, [A-Za-z]+-MBP, MacBook-Pro\.local, MacBook-Air\.local, [A-Za-z]+s-Mac[A-Za-z-]*
- Usernames in paths:
/Users/[a-z]+, /home/[a-z]+ (but only when they appear to be real usernames, not placeholder patterns in docs)
- Personal names in comments/docs: Look for patterns like
author:, created by, @author, Copyright [Year] [Name] where the name is a real person (not a company)
- IP addresses:
\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b — flag private/internal IPs that might reveal network topology
Exclusions
- Ignore files in
.git/, node_modules/, vendor/, dist/, build/
- Ignore binary files (images, fonts, compiled assets)
- Ignore
package-lock.json, yarn.lock, Cargo.lock
- Ignore example/placeholder emails like
user@example.com, foo@bar.com
Scanner 2: Secrets Scanner
Severity: CRITICAL
Search for API keys, tokens, passwords, and credentials that must never be in a public repository.
What to scan for
Use Grep with these patterns:
- AWS keys:
AKIA[0-9A-Z]{16}, aws_secret_access_key, aws_access_key_id
- GitHub tokens:
gh[pousr]_[A-Za-z0-9_]{36,}, github_pat_[A-Za-z0-9_]{22,}
- Generic API keys:
(?i)(api[_-]?key|apikey|api[_-]?secret)\s*[:=]\s*['"]?[A-Za-z0-9_-]{16,}['"]?
- Generic tokens:
(?i)(token|auth[_-]?token|bearer|access[_-]?token)\s*[:=]\s*['"]?[A-Za-z0-9_.-]{20,}['"]?
- Generic passwords:
(?i)(password|passwd|pwd)\s*[:=]\s*['"]?[^\s'"]{8,}['"]?
- Private keys:
-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----
- Slack webhooks:
https://hooks\.slack\.com/services/T[A-Z0-9]+/B[A-Z0-9]+/[A-Za-z0-9]+
- Database URLs:
(?i)(mongodb|postgres|mysql|redis|amqp)://[^\s'"]+
- Google API keys:
AIza[0-9A-Za-z_-]{35}
- Stripe keys:
(?:sk|pk)_(test|live)_[A-Za-z0-9]{24,}
- .env files present: Check if
.env, .env.local, .env.production, .env.development exist and are NOT in .gitignore
Exclusions
- Ignore lock files (
package-lock.json, yarn.lock, etc.)
- Ignore
.git/ directory
- Ignore test fixtures that explicitly use fake/placeholder values (e.g.,
test_key_12345, EXAMPLE_API_KEY)
- Ignore patterns in documentation that are clearly examples (look for surrounding context like "example", "placeholder", "replace with")
Scanner 3: Path Hardcoding Scanner
Severity: MEDIUM
Search for paths that are specific to a particular machine or user and won't work on other systems.
What to scan for
Use Grep with these patterns:
- User home directories:
/Users/[a-zA-Z]+/, /home/[a-zA-Z]+/
- macOS-specific paths:
/opt/homebrew/, /usr/local/Cellar/, /Applications/
- Windows-specific paths:
C:\\Users\\, C:\\Program Files
- Hardcoded tmp paths:
/tmp/[a-zA-Z]+ (specific named temp dirs, not generic /tmp)
- Workspace/project paths:
/workplace/, /workspace/, /Projects/, /Development/
- Architecture-specific:
/usr/lib/x86_64, /usr/lib/aarch64
Exclusions
- Ignore paths that are in documentation explaining what to replace
- Ignore paths in
.gitignore (those are configuration, not code)
- Ignore paths in lock files
- Ignore
/Users/ or /home/ when part of a regex pattern being used for scanning (meta-usage)
- Ignore this SKILL.md file itself (it contains example patterns)
Scanner 4: License Checker
Severity: MEDIUM
Verify the repository has a proper open-source license.
What to check
- Use Glob to look for:
LICENSE, LICENSE.md, LICENSE.txt, LICENCE, LICENCE.md, LICENCE.txt, COPYING
- If found, Read the file and verify it contains recognized license text:
- MIT: Look for "MIT License" or "Permission is hereby granted"
- Apache-2.0: Look for "Apache License" and "Version 2.0"
- GPL: Look for "GNU GENERAL PUBLIC LICENSE"
- BSD: Look for "BSD" and "Redistribution and use"
- ISC: Look for "ISC License"
- MPL: Look for "Mozilla Public License"
- If NO license file found: Flag as MEDIUM severity
- If license file exists but doesn't match any known pattern: Flag as LOW (might be custom)
- Check
package.json (if exists) for license field consistency
Scanner 5: Gitignore Auditor
Severity: LOW
Check that the repository has a proper .gitignore that excludes common sensitive and unnecessary files.
What to check
- Verify
.gitignore exists at repo root
- If it exists, Read it and check for these common entries:
Should be present (flag if missing):
.env (or .env*).DS_Storenode_modules/ (if package.json exists)__pycache__/ or *.pyc (if any .py files exist)dist/ or build/ (if build system detected).idea/, .vscode/ (IDE configs)*.logcoverage/ (if test framework detected)target/ (if Cargo.toml exists).terraform/ (if any .tf files exist)
- Check if any files that SHOULD be ignored are actually tracked:
- Use
git ls-files to see if .env, .DS_Store, or IDE config files are tracked
Scanner 6: Git History Auditor
Severity: HIGH
Check git history for author information that reveals personal details or machine-specific identifiers.
What to check
- Run:
git log --format='%ae' | sort -u to get unique author emails
- Flag emails that contain:
- Machine hostnames:
@.*MacBook, @.*\.local, @.*\.internal
- Generic local addresses:
@localhost, @127.0.0.1
- Personal domain emails that might not be intended for public (flag but don't auto-classify)
- Run:
git log --format='%an' | sort -u to get unique author names
- Cross-reference with PII findings — flag if author names appear hardcoded elsewhere in the repo
- Note: Git history is hard to rewrite. If issues are found, recommend
git filter-branch or git-filter-repo as remediation, and warn about force-push implications.
Feature 2: Repo Health Scorecard
Run in: FULL mode, HEALTH mode
Scan for GitHub community health files and produce a weighted score with letter grade.
Health Checks
| Check | Weight | How to Scan |
|---|
| README.md exists and has content | 15 | Glob for README.md/README/readme.md, Read and check length > 50 lines or > 500 chars |
| LICENSE file exists and is recognized | 15 | Glob for LICENSE*/LICENCE*/COPYING, Read and match known licenses |
| CONTRIBUTING.md exists | 10 | Glob for CONTRIBUTING.md/CONTRIBUTING/.github/CONTRIBUTING.md |
| CODE_OF_CONDUCT.md exists | 10 | Glob for CODE_OF_CONDUCT.md/.github/CODE_OF_CONDUCT.md |
| SECURITY.md exists | 10 | Glob for SECURITY.md/.github/SECURITY.md |
| .gitignore exists and is comprehensive | 10 | Glob + Read, check it has >= 5 entries |
| Issue templates exist | 5 | Glob for .github/ISSUE_TEMPLATE/ or .github/ISSUE_TEMPLATE.md |
| PR template exists | 5 | Glob for .github/pull_request_template.md or .github/PULL_REQUEST_TEMPLATE.md |
| CHANGELOG.md exists | 5 | Glob for CHANGELOG.md/CHANGELOG/HISTORY.md/CHANGES.md |
| FUNDING.yml exists | 5 | Glob for .github/FUNDING.yml |
| CI config exists | 5 | Glob for .github/workflows/*.yml or .circleci/config.yml or Jenkinsfile or .travis.yml or .gitlab-ci.yml |
| CODEOWNERS exists | 5 | Glob for CODEOWNERS/.github/CODEOWNERS/docs/CODEOWNERS |
Total possible: 100 points
Grading Scale
| Grade | Score Range |
|---|
| A+ | 95–100 |
| A | 90–94 |
| A- | 85–89 |
| B+ | 80–84 |
| B | 75–79 |
| B- | 70–74 |
| C+ | 65–69 |
| C | 60–64 |
| C- | 55–59 |
| D | 50–54 |
| F | 0–49 |
Output Format (Standalone)
══════════════════════════════════════════
REPO HEALTH SCORECARD
{repo-name} | {date}
══════════════════════════════════════════
GRADE: 🏆 {letter-grade} SCORE: {points}/100
──────────────────────────────────────────
✅ README.md ███████████████ 15/15
✅ LICENSE ███████████████ 15/15
❌ CONTRIBUTING.md ░░░░░░░░░░░░░░ 0/10
❌ CODE_OF_CONDUCT.md ░░░░░░░░░░░░░░ 0/10
❌ SECURITY.md ░░░░░░░░░░░░░░ 0/10
✅ .gitignore ██████████░░░░ 10/10
❌ Issue templates ░░░░░░░░░░░░░░ 0/5
❌ PR template ░░░░░░░░░░░░░░ 0/5
❌ CHANGELOG.md ░░░░░░░░░░░░░░ 0/5
❌ FUNDING.yml ░░░░░░░░░░░░░░ 0/5
❌ CI config ░░░░░░░░░░░░░░ 0/5
❌ CODEOWNERS ░░░░░░░░░░░░░░ 0/5
──────────────────────────────────────────
📋 Missing Files (create these to improve your score):
- CONTRIBUTING.md — Tell contributors how to help
- CODE_OF_CONDUCT.md — Set community expectations
- SECURITY.md — Describe vulnerability reporting process
...
══════════════════════════════════════════
Use ████ (U+2588 FULL BLOCK) for filled portions and ░░░░ (U+2591 LIGHT SHADE) for empty portions. Scale the bar width proportionally to the item's max weight.
Feature 3: Open Source Coach
Run in: COACH mode only (never in FULL mode — this is interactive)
This is an interactive conversational session. Ask questions ONE AT A TIME and wait for the user's response before proceeding to the next question. Do NOT dump all questions at once.
Conversation Flow
Step 1 — Understand the Project
Ask: "What does this project do? Give me the elevator pitch."
While waiting, scan the repo (Read README, check package.json/Cargo.toml for description, look at directory structure) to form your own understanding.
Step 2 — Check the Landscape
Ask: "Does something similar already exist as open source? Who are the closest competitors/alternatives?"
Share what you found from scanning the repo to help the user think through this.
Step 3 — Clarify Goals
Ask: "What's your main goal for open sourcing? (Pick the top 1-2)"
Offer options:
- Community adoption and contributors
- Portfolio/resume building
- Industry credibility
- Giving back to the community
- Company mandate/strategy
Step 4 — Assess Maintenance Capacity
Ask: "Can you commit to maintaining this? Think about: responding to issues, reviewing PRs, updating dependencies."
Estimate effort based on repo size and complexity you observed.
Step 5 — IP and Legal Check
Ask: "Any intellectual property or legal concerns? Does this contain company code, proprietary algorithms, or dependencies with restrictive licenses?"
Scan for license files of dependencies if possible.
Step 6 — License Recommendation
Based on the user's goals, recommend a license:
- Adoption-focused: MIT or Apache-2.0 (permissive, maximum adoption)
- Protection-focused: GPL or AGPL (copyleft, ensures derivatives stay open)
- Company/dual-license: Apache-2.0 with CLA (corporate-friendly)
- Creative work: CC-BY or CC-BY-SA
Explain the tradeoffs briefly.
Step 7 — Positioning Advice
Based on everything discussed, provide:
- Suggested README framing (what hook to lead with)
- Where to announce (Hacker News, Reddit, Twitter/X, dev.to, relevant Discord/Slack communities)
- Timing advice (avoid major conference days, launch on Tuesday-Thursday for visibility)
Final Output
After all 7 steps, summarize as:
══════════════════════════════════════════
OPEN SOURCE COACH — SUMMARY
══════════════════════════════════════════
VERDICT: {GO / HOLD / RECONSIDER}
📋 Recommendation:
{2-3 sentence summary}
📝 Next Steps:
1. {action item}
2. {action item}
3. {action item}
...
══════════════════════════════════════════
Feature 4: README Auditor
Run in: FULL mode, README mode
Score the existing README against best practices. If no README exists, report that immediately with a template suggestion.
Scoring Criteria
| Section | Points | How to Check |
|---|
| Project title + description | 10 | First H1 heading exists with clear name, followed by one-line description |
| Badges | 5 | Has at least 1 badge (look for ![ patterns with shields.io, badge URLs, or similar) |
| Installation instructions | 15 | Has section matching install/setup/getting started with code blocks (``` or indented) |
| Usage examples | 15 | Has section matching usage/example/quick start with code blocks |
| API documentation or link | 10 | Has section matching api/reference/docs OR links to external docs site |
| Contributing section or link | 10 | Has section matching contribut OR links to CONTRIBUTING.md |
| License mention | 10 | Mentions license name or links to LICENSE file |
| Table of contents | 5 | Has TOC (look for linked list of sections) — only score if README > 100 lines |
| Screenshots/diagrams | 10 | Has images (![, <img), GIFs, or diagrams (mermaid blocks, ASCII art) |
| Contact/support info | 5 | Has section matching support/contact/help OR links to issues/discussions |
| No malformed links | 5 | Check for syntactic link issues: empty (), [text](), relative links to non-existent files (does NOT verify external URLs) |
Total possible: 100 points (95 if README <= 100 lines, since TOC is not expected)
Output Format
══════════════════════════════════════════
README AUDIT
{repo-name} | {date}
══════════════════════════════════════════
SCORE: {points}/100 GRADE: {letter-grade}
──────────────────────────────────────────
```diff
+ Title & description 10/10 Clear project name and purpose
+ Installation instructions 15/15 Has setup section with code blocks
- Usage examples 0/15 No usage section found
- Badges 0/5 No badges detected
+ License mention 10/10 MIT license referenced
- Screenshots/diagrams 0/10 No visual aids found
...
📋 Suggestions:
1. Add a "Usage" section with code examples showing common use cases
2. Add badges for license, CI status, and version
3. Add a screenshot or architecture diagram
...
══════════════════════════════════════════
Section-by-section scoring tells the user exactly what to improve.
---
## Feature 5: Release Readiness Check
**Run in: FULL mode, RELEASE mode**
Pre-push checklist for release readiness. Run each check and report pass/fail.
### Checks
| Check | Severity | How to Scan |
|-------|----------|-------------|
| CHANGELOG.md exists and has entries | HIGH | Glob for `CHANGELOG.md`, Read and verify it has content beyond a template |
| Latest version tag exists | MEDIUM | Run `git tag --sort=-v:refname \| head -5` to check for version tags |
| No TODO/FIXME/HACK in code | LOW | Grep for `TODO`, `FIXME`, `HACK` patterns (exclude vendor/node_modules) |
| No console.log/print debug statements | LOW | Grep for `console\.log`, `print(` (in non-Python contexts), `debugger`, `binding\.pry`, `pp `, `var_dump` |
| Package version matches git tag | MEDIUM | Read `package.json`/`Cargo.toml`/`pyproject.toml` version, compare to latest git tag |
| Build succeeds | HIGH | Detect build system (package.json scripts, Makefile, Cargo.toml) and report what to run — do NOT run builds automatically |
| Tests pass | HIGH | Detect test runner and report what to run — do NOT run tests automatically |
| No uncommitted changes | HIGH | Run `git status --porcelain` |
| Branch is up to date with remote | MEDIUM | Run `git fetch --dry-run 2>&1` to check without modifying |
| .env.example exists if .env is in .gitignore | LOW | Check if `.gitignore` contains `.env` AND if `.env.example` or `.env.sample` exists |
### Output Format
```text
══════════════════════════════════════════
RELEASE READINESS CHECK
{repo-name} | {date}
══════════════════════════════════════════
VERDICT: {READY TO SHIP | NEEDS WORK | NOT READY}
──────────────────────────────────────────
```diff
+ No uncommitted changes
+ Branch up to date with remote
+ No secrets detected
- CHANGELOG.md missing or empty
- No version tags found
! 3 TODO comments found in source code
! 2 console.log statements found
+ .env.example exists
- Build command not verified (run: npm run build)
- Tests not verified (run: npm test)
📋 Action Items:
1. [HIGH] Create CHANGELOG.md with release notes
2. [HIGH] Run build and tests manually before release
3. [MEDIUM] Create a version tag: git tag v1.0.0
4. [LOW] Resolve 3 TODO comments or convert to GitHub Issues
5. [LOW] Remove 2 debug console.log statements
══════════════════════════════════════════
Use `+` for pass, `-` for fail, `!` for warning in the diff block.
### Verdict Logic (Release)
- **READY TO SHIP**: 0 HIGH failures
- **NEEDS WORK**: 1+ HIGH failures
Note: In standalone RELEASE mode, the verdict is only READY TO SHIP or NEEDS WORK. The NOT READY verdict (for CRITICAL security issues) only applies when running in FULL mode alongside the Security Scanner.
---
## Report Generation (Full Audit Mode)
When running in FULL mode, aggregate ALL feature results into a combined report.
**Important**: In FULL mode, run Feature 1 (Security Scanner), Feature 2 (Repo Health Scorecard), Feature 4 (README Auditor), and Feature 5 (Release Readiness Check) as parallel subagents. Feature 3 (Open Source Coach) is NEVER included in FULL mode — it is interactive-only.
### Combined Report Format
```text
══════════════════════════════════════════
OPEN SOURCE READINESS REPORT
{repo-name} | {date}
══════════════════════════════════════════
GRADE: 🏆 {letter-grade} VERDICT: {READY | NEEDS WORK | NOT READY}
──────────────────────────────────────────
🔒 Security {bar} {pct}%
📋 Repo Health {bar} {pct}%
📖 README {bar} {pct}%
🚀 Release {bar} {pct}%
──────────────────────────────────────────
## Security Findings
{Feature 1 results — findings by severity}
## Repo Health
{Feature 2 results — file-by-file scorecard}
## README Quality
{Feature 4 results — section-by-section scoring}
## Release Readiness
{Feature 5 results — pass/fail checklist}
──────────────────────────────────────────
## Remediation Steps (Priority Order)
1. 🔴 CRITICAL: {items from security scanner}
2. 🟠 HIGH: {items from security + release checks}
3. 🟡 MEDIUM: {items from all features}
4. ⚪ LOW: {items from all features}
══════════════════════════════════════════
Scoring (Combined Grade)
Calculate overall score as weighted average:
- Security: 35% weight (most important)
- Repo Health: 25% weight
- README: 20% weight
- Release: 20% weight
Security scoring: Start at 100%, subtract 25% per CRITICAL, 15% per HIGH, 5% per MEDIUM, 2% per LOW. Floor at 0%.
Release scoring: Each check is worth equal points (10% each, 10 checks = 100%).
Use the same A+ through F grading scale as Repo Health.
Overall Verdict Logic
- READY: Overall grade >= B- AND 0 CRITICAL security findings
- NEEDS WORK: Overall grade >= D OR has HIGH but no CRITICAL findings
- NOT READY: Any CRITICAL security findings OR overall grade < D
Progress Bars
Use 10-character bars:
- 0%:
░░░░░░░░░░
- 10%:
█░░░░░░░░░
- 20%:
██░░░░░░░░
- 30%:
███░░░░░░░
- ...
- 100%:
██████████
Color code with emoji prefix:
- 🟢 80-100%
- 🟡 50-79%
- 🔴 0-49%
Self-Exclusion
When scanning, EXCLUDE these files from findings (they are part of the skill itself or infrastructure):
- This
SKILL.md file
- Files in the
evals/ directory
- Files in
.loki/ directory
- Files in
.claude/ directory
- Files in
openspec/ directory
Edge Cases
- No git history: Skip Git History Auditor, note in report
- No README: README Auditor reports score of 0 with template suggestion
- Binary-heavy repos: Note that binary files were skipped, recommend manual review
- Monorepos: Scan the full repo but organize findings by directory
- Empty repos: Report "No files to scan" with READY verdict
- Very large repos (1000+ files): Use Glob to get file list first, then scan in batches to avoid overwhelming context
- Coach mode in full audit: Skip — Coach is interactive-only and not included in automated full audit
