repo-ready

Files (17)

• .gitignore
• .npmrc
• .vally.yaml
• LICENSE
• README.md
• SKILL.md
• README.md · evals/
• eval.yaml · evals/repo-ready/
• package-lock.json
• package.json
• detect-stack.mjs · scripts/
• generate.mjs · scripts/
• scan-repo.mjs · scripts/
• detect.test.mjs · test/
• generate.test.mjs · test/
• scan.test.mjs · test/
• thumbnail.png

SKILL.md (first lines)

# Repo Ready

Scaffold or audit standard GitHub repository files, adapting them to the project's stack, audience, and governance.

## Two modes

### Init mode (bare `repo-ready` or `repo-ready init`)

Start from scratch. Interview the user to understand the project, then
scaffold every file in one pass.

### Update mode (`repo-ready update`)

Scan an existing repo, compare against the full checklist, report what's
missing or outdated, and offer to create each missing file interactively.

Both modes use the same interview/guidance engine and the same file catalog.
The difference is scope: init creates everything; update creates only what's
missing.

## The file catalog

Every file this skill knows about, grouped by category. The generator
(`scripts/generate.mjs`) produces each one from templates plus user answers.

### Tier 1: Essential (every repo should have these)

| File | Purpose | GitHub behavior |
|------|---------|-----------------|
| `.gitignore` | Exclude build artifacts, deps, OS files | New-repo UI offers language picker |
| `.gitattributes` | Line endings, binary handling, linguist | Powers language stats, diff behavior |
| `LICENSE` | Legal permissions for use/modification | Sidebar badge, license detection, search filter |
| `README.md` | Project introduction and docs | Rendered on repo homepage |

### Tier 2: Community health (open source and team projects)

| File | Purpose | GitHub behavior |
|------|---------|-----------------|
| `CONTRIBUTING.md` | How to contribute | Banner on new issues/PRs |
| `CODE_OF_CONDUCT.md` | Community standards | Community profile checklist, tab in repo |
| `SECURITY.md` | Vulnerability disclosure policy | Security tab, community profile checklist |
| `.github/ISSUE_TEMPLATE/bug_report.yml` | Structured bug reports | Issue template chooser |
| `.github/ISSUE_TEMPLATE/feature_request.yml` | Structured feature requests | Issue template chooser |
| `.github/ISSUE_TEMPLATE/config.yml` | Template chooser config | Controls blank issues, external links |
| `.github/PULL_REQUEST_TEMPLATE.md` | PR body template | Auto-fills PR description |

### Tier 3: Automation and governance

| File | Purpose | GitHub behavior |
|------|---------|-----------------|
| `.github/dependabot.yml` | Automated dependency updates | Dependabot opens PRs on schedule |
| `.github/workflows/ci.yml` | CI pipeline (build + test) | Actions tab, PR status checks |
| `.github/CODEOWNERS` | Auto-assign PR reviewers by path | Review requests, branch protection |
| `.github/FUNDING.yml` | Sponsor button | Heart icon on repo page |
| `CHANGELOG.md` | Version history | Human-readable release notes |

### Tier 4: Editor and tooling (stack-dependent)

| File | Purpose | When to include |
|------|---------|-----------------|
| `.editorconfig` | Cross-editor formatting | Always (universal) |
| `.markdownlint.json` | Markdown style consistency | Repos with significant Markdown |
| `.prettierrc` | Code formatter config | JS/TS projects |
| `.eslintrc` / `eslint.config.js` | Linting config | JS/TS projects |

### Tier 5: Repo metadata (GitHub API settings)

These aren't files; they're repository settings managed via `gh` CLI / GitHub
API. The skill audits and updates them as part of both init and update modes.

| Setting | Purpose | How to check | How to set |
|---------|---------|--------------|------------|
| Description | One-line "About" text on repo page | `gh repo view --json description` | `gh repo edit --description "..."` |
| Topics | Searchable tags (shown as badges) | `gh repo view --json repositoryTopics` | `gh api -X PUT repos/{owner}/{repo}/topics -f "names[]=..."` |
| Website | Homepage URL in repo sidebar | `gh repo view --json homepageUrl` | `gh repo edit --homepage "..."` |
| Social preview | OpenGraph image for link sharing | GitHub web UI only | Cannot be set via API (inform user) |

### Tier 6: Supplementary (situational)

| File | Purpose | When to include |
|------|---------|-----------------|
| `SUPPORT.md` | Where to get help | Projects with forums/Discord/SO presence |
| `CITATION.cff` | Academic citation metadata | Research/academic software |
| `.github/DISCUSSION_TEMPLATE/` | Structured discussion forms | Repos using GitHub Discussions |

## Interview protocol

**Never scaffold on a guess.** Every file involves choices (which license? what
stack for .gitignore? who are the codeowners?). Interview the user to make
informed decisions.

### Interview flow

Ask one question at a time using `ask_user`. Skip any question the user already
answered in their prompt. Confirm inferred answers in one line before
scaffolding.

#### Phase 1: Project context (always detect, then ask)

1. **Stack detection** (auto): Scan the repo for lockfiles, manifests, and
   source files. Detect: `package.json`/`pnpm-lock.yaml`/`yarn.lock` (Node.js),
   `requirements.txt`/`pyproject.toml`/`Pipfile` (Python), `go.mod` (Go),
   `Cargo.toml` (Rust), `*.csproj`/`*.sln` (.NET), `pom.xml`/`build.gradle`
   (Java), `Gemfile` (Ruby), `Dockerfile`, `terraform/` (IaC). Report what you
   found: "Detected: Node.js (pnpm), TypeScript, Docker."

2. **Repo visibility** (auto-detect, NEVER guess): Run
   `gh api repos/{owner}/{repo} --jq '.private'` to determine if the repo is
   public or private. This is authoritative. Do NOT infer visibility from the
   repo name, description, or any other heuristic. If `gh` is unavailable or
   the command fails, ask the user explicitly. Report what you found:
   "Repo visibility: private" or "Repo visibility: public".

3. **Project type**: Is this a library/package, a CLI tool, a web app, an API
   service, a monorepo, or something else? (Affects README structure,
   CONTRIBUTING guidance, CI workflow.)

4. **Audience**: Based on the detected visibility, set the default:
   - **Private repo** -> default to "internal/personal". Ask: "This is a

From jongio/skills, MIT.

More from jongio/skills