# Github Audit

> Audits a GitHub repository against best practices and provides prioritized recommendations for README, license, community health, CI/CD, and repository settings.

- Skill: `thijsvos/github-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add thijsvos/github-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thijsvos/github-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: thijsvos (https://skillmd.com/u/thijsvos)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thijsvos/github-audit

---


Call `EnterPlanMode` immediately before doing anything else.

You are about to perform a comprehensive audit of this GitHub repository against GitHub best practices. Your goal is to identify what's missing, what's incomplete, and what can be improved — then present a prioritized, actionable list of recommendations.

Execute each phase thoroughly before moving to the next. Use subagents for parallel exploration wherever possible.

**Ask the user questions when it would improve the result.** For example: after Phase 1, ask about the project's intended audience (public library vs internal tool vs personal project) since this affects which best practices matter most.

**IMPORTANT:** All subagents MUST be launched with `agentType: 'Explore'` inside the `Workflow` script (omit `model` — each agent inherits the session model), or, on the `Agent`-tool fallback, with `subagent_type: "Explore"` and `model: "opus"` (resolves to the latest Claude Opus, the most capable model). The Explore agent is read-only by design (Edit and Write are denied at the agent level). This ensures no subagent can accidentally modify the project during analysis. The explicit `model: "opus"` on the `Agent` path pins the fan-out to the latest Opus even when a cheaper default subagent model is configured, so the analysis never silently runs on a smaller model. Never use general-purpose subagents in this skill.

## Pre-rendered context

The harness pre-renders the repository identity and a few scoping checks (Claude Code dynamic context injection) so Phase 1 doesn't re-run the same `gh` commands. Substitute the resolved `slug`/`default_branch` directly into the API paths in Phase 1's Agent 3.

- **Repo slug (`owner/name`):** !`gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null || echo "(gh unavailable or not a github remote)"`
- **Default branch:** !`gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null || echo "(unknown)"`
- **License:** !`gh repo view --json licenseInfo --jq '.licenseInfo.spdxId // "(none detected)"' 2>/dev/null || echo "(gh unavailable)"`
- **Topics:** !`gh repo view --json repositoryTopics --jq '[.repositoryTopics[].name] | join(",")' 2>/dev/null || echo "(none)"`
- **Workflows present:** !`ls -1 .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | head -10 || echo "(none)"`

If `Repo slug` is `(gh unavailable...)`, stop in Phase 1 with an actionable error explaining that `gh` must be authenticated and the remote must be GitHub. Otherwise use the resolved slug in subsequent `gh api repos/<slug>/...` calls.

---

## Phase 1: Repository Scan

Run the scan as a **`Workflow` of exactly 3 read-only Explore agents in parallel** to gather data on all GitHub-relevant aspects of the repository. Call the `Workflow` tool with a script along these lines, substituting the pre-rendered context and each agent's brief verbatim from its `### Agent N` section. The IMPORTANT block above governs how every subagent must be configured.

```js
export const meta = {
  name: 'github-audit-scan',
  description: 'Three-lens repository scan: files & structure, README, GitHub settings & CI/CD',
  phases: [{ title: 'Scan' }],
}

const CONTEXT = `<the pre-rendered repo slug, default branch, license, topics, and workflow list>`

const LENSES = [
  { key: 'files-structure', brief: `<Agent 1 brief, verbatim>` },
  { key: 'readme',          brief: `<Agent 2 brief, verbatim>` },
  { key: 'settings-cicd',   brief: `<Agent 3 brief, verbatim>` },
]

const reports = await parallel(LENSES.map(l => () =>
  agent(`Scan this repository through the ${l.key} lens and return what you find, noting anything missing.\n${CONTEXT}\n\n${l.brief}`,
    { label: `scan:${l.key}`, phase: 'Scan', agentType: 'Explore' })))

return { lenses: LENSES.map((l, i) => ({ key: l.key, report: reports[i] })) }
```

Wait for the Workflow's completion notification before continuing — never evaluate from partial results. A `null` report means that agent was skipped or failed; note the gap in the scorecard rather than silently dropping the lens.

**Fallback.** If the `Workflow` tool is not available in this session, launch the same three briefs as **3 Explore subagents in parallel** via the `Agent` tool (`subagent_type: "Explore"`, `model: "opus"`).

### Agent 1: File & Structure Audit

Scan for the presence, location, and quality of these files:

- `README.md` (or `README`, `readme.md`)
- `LICENSE` (or `LICENSE.md`, `LICENCE`, `COPYING`)
- `.gitignore`
- `CHANGELOG.md` (or `CHANGES.md`, `HISTORY.md`)
- `CONTRIBUTING.md`
- `CODE_OF_CONDUCT.md`
- `SECURITY.md`
- `.github/FUNDING.yml`
- `.github/ISSUE_TEMPLATE/` or `.github/ISSUE_TEMPLATE.md`
- `.github/PULL_REQUEST_TEMPLATE.md` or `.github/PULL_REQUEST_TEMPLATE/`
- `.github/DISCUSSION_TEMPLATE/`
- `.github/workflows/` (GitHub Actions)
- `.github/dependabot.yml`
- `.github/CODEOWNERS`
- `docs/` directory
- `.editorconfig`

Read each file that exists. Note which are missing entirely.

### Agent 2: README Deep Analysis

If a README exists, evaluate it against these criteria:

- **Project title and description** — Is it clear what this project does?
- **Badges** — Build status, version, license, coverage, etc.
- **Installation instructions** — Can someone get started quickly?
- **Usage examples** — Are there code snippets or command examples?
- **Configuration / API reference** — For libraries/tools, is the interface documented?
- **Screenshots or visuals** — For UI projects, are there screenshots or demos?
- **Contributing section** — Is there a link to CONTRIBUTING.md or inline guidelines?
- **License section** — Is the license mentioned/linked?
- **Table of contents** — For longer READMEs, is navigation provided?
- **Links to documentation** — If there are docs, are they linked?
- **Contact / support** — How to get help or report issues?

### Agent 3: GitHub Settings & CI/CD

Use bash commands to check:

```bash
# Check if this is a git repo and has a remote
git remote -v 2>/dev/null

# Check branch setup
git branch -a 2>/dev/null

# Check if there's a default branch protection indicator
# (look for branch protection in CI/CD workflows)
ls -la .github/workflows/ 2>/dev/null

# Check git tags (releases)
git tag -l 2>/dev/null | tail -20

# Check recent commit patterns
git log --oneline -20 2>/dev/null

# Check .gitignore coverage - look for common files that shouldn't be committed
# (node_modules, .env, __pycache__, .DS_Store, etc.)
cat .gitignore 2>/dev/null
```

If the repo has a GitHub remote, use `gh` CLI to check. First resolve the repo slug and default branch so the API paths can be substituted explicitly (`gh api` does not auto-expand `{owner}/{repo}` placeholders):

```bash
# Repository metadata (also yields the slug and default branch)
gh repo view --json name,description,url,homepageUrl,isPrivate,hasIssuesEnabled,hasWikiEnabled,hasDiscussionsEnabled,hasProjectsEnabled,licenseInfo,repositoryTopics,defaultBranchRef,stargazerCount,forkCount 2>/dev/null

# Resolve slug and default branch for the subsequent API calls
slug=$(gh repo view --json nameWithOwner --jq .nameWithOwner 2>/dev/null)
default_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)

# Check if GitHub Pages is enabled
[ -n "$slug" ] && gh api "repos/$slug/pages" 2>/dev/null

# Check branch protection rules on the actual default branch (not a guess of main/master)
[ -n "$slug" ] && [ -n "$default_branch" ] && gh api "repos/$slug/branches/$default_branch/protection" 2>/dev/null

# Check if Dependabot alerts are enabled
[ -n "$slug" ] && gh api "repos/$slug/vulnerability-alerts" 2>/dev/null

# Check releases
gh release list --limit 5 2>/dev/null

# Check secrets scanning
[ -n "$slug" ] && gh api "repos/$slug/secret-scanning/alerts" --paginate 2>/dev/null | head -5
```

Note: many of these commands may fail on private repos or repos without certain features enabled. That's fine — a failed check is itself a finding.

---

## Phase 2: Best Practices Evaluation

Based on Phase 1 findings, evaluate the repository across these categories. For each category, assign a status:

- **Good** — Meets or exceeds best practices
- **Needs improvement** — Exists but incomplete or outdated
- **Missing** — Not present at all
- **N/A** — Not applicable for this project type

### Categories

**1. README Quality**
- Does it clearly explain what the project is?
- Can a new user get started in under 5 minutes?
- Are there usage examples?
- Is it well-structured and scannable?

**2. License**
- Is a license file present?
- Is it a recognized open-source license?
- Is it referenced in the README?
- Is it appropriate for the project type?

**3. Community Health**
- Contributing guidelines (CONTRIBUTING.md)
- Code of conduct (CODE_OF_CONDUCT.md)
- Security policy (SECURITY.md)
- Issue templates
- PR templates
- CODEOWNERS

**4. CI/CD & Automation**
- GitHub Actions workflows present?
- Are tests automated?
- Is there a build/lint step?
- Dependabot configured?
- Release automation?

**5. Repository Settings**
- Description set?
- Topics/tags added?
- Homepage URL set (if applicable)?
- Issues enabled?
- Discussions enabled (if appropriate)?
- Wiki configured or disabled?
- Social preview / branding?

**6. Git Hygiene**
- .gitignore comprehensive for the project's tech stack?
- No committed secrets or sensitive files?
- Meaningful commit messages?
- Branch strategy evident?
- Tags/releases used?

**7. Documentation**
- Is documentation sufficient for the project's complexity?
- API docs for libraries?
- Architecture docs for complex projects?
- Changelog maintained?

---

## Phase 3: Prioritized Recommendations

Present your findings in this format:

### Repository Scorecard

| Category | Status | Priority |
|----------|--------|----------|
| README Quality | Good / Needs improvement / Missing | High / Medium / Low |
| License | ... | ... |
| Community Health | ... | ... |
| CI/CD & Automation | ... | ... |
| Repository Settings | ... | ... |
| Git Hygiene | ... | ... |
| Documentation | ... | ... |

### Top Recommendations

For each recommendation (ordered by priority):

#### 1. [Recommendation Title]
**Category**: Which category this falls under
**Effort**: Quick fix (< 5 min) / Small (< 30 min) / Medium (< 2 hours)
**Impact**: Why this matters

**What to do:**
Specific, actionable steps. Include example content, commands, or file templates where helpful.

---

Aim for 5-10 concrete recommendations. Focus on what would have the most impact for this specific project — not a generic checklist. Consider the project's type, audience, and maturity stage when prioritizing.

**Skill handoff.** If a recommendation maps cleanly to another installed skill in this collection, suggest invoking it via the `Skill` tool instead of implementing manually. Examples:
- "Dependencies are stale / no Dependabot configured" → suggest `/dep-check`
- "No tests" or "test coverage gaps" → suggest `/test-gen`
- "Missing docstrings on public API" → suggest `/docstring-check`
- "Code smells / refactoring opportunities surfaced by the audit" → suggest `/refactor`
- "Ready to ship a fix and you don't have a PR workflow set up" → suggest `/github-ship`

After presenting the full audit, call `ExitPlanMode`, then ask: **"Want me to implement any of these recommendations?"**