repo-scaffold

Repo Scaffold

Initialize GitHub repositories with standard files and configuration. This skill generates LICENSE, CONTRIBUTING.md, SECURITY.md, CODEOWNERS, .gitignore, .editorconfig, YAML-based issue templates, PR template, CI config skeleton, and optional safety files. It detects project type from existing files and adapts all templates accordingly.

Install

claude skill install repo-scaffold

When to Use

This skill should be used when:

• Setting up a new GitHub repository from scratch
• Adding missing standard files to an existing repository
• Standardizing repository configuration across projects
• Preparing a private repo for open-source release

Usage

/repo-scaffold [repo-path] [--license MIT|Apache-2.0|ISC] [--public] [--ci github-actions|none]

Flag	Default	Description
repo-path	. (cwd)	Path to the git repository root
--license	MIT	License type (MIT, Apache-2.0, ISC, GPL-3.0, BSD-2-Clause)
--public	off	Include .public-repo, .pii-allowlist, .commit-msg-blocklist
--ci	github-actions	CI provider skeleton (github-actions or none)

Procedure

Step 1: Validate Repo Path

Confirm the target path is an initialized git repository (contains .git/). If not, halt and inform the user. Never run git init without explicit permission.

Step 2: Scan Existing Files

Inventory the repo root and .github/ directory for any files this skill would generate. Build a conflict list. Never overwrite existing files. If conflicts exist, present them and ask which to skip or replace.

Step 3: Detect Project Type

Identify the primary language and tooling by checking for marker files:

Marker File	Project Type
package.json	Node.js / JavaScript / TypeScript
pyproject.toml, setup.py, requirements.txt	Python
Cargo.toml	Rust
go.mod	Go
Multiple markers	Multi-language
None of the above	Generic

If multiple markers are found, treat as multi-language and combine relevant patterns.

Step 4: Generate Files

Generate each file with language-appropriate content. Refer to REFERENCE.md for templates, patterns, and format specifications.

4a. LICENSE

Prompt the user for license choice if --license was not provided. Default to MIT. Insert the current year and the repo owner's name (from git config user.name or ask). See REFERENCE.md license comparison table for guidance.

4b. .gitignore

Generate language-appropriate ignore patterns based on the detected project type. Combine patterns for multi-language repos. Always include OS-level ignores (.DS_Store, Thumbs.db) and editor ignores (.vscode/, .idea/).

4c. CONTRIBUTING.md

Generate a fork-branch-PR contribution guide. Include:

• Fork and clone instructions
• Branch naming conventions (feat/, fix/, docs/)
• Code style notes (link to linter config if detected)
• Commit message format
• PR checklist

4d. SECURITY.md

Generate a security policy with:

• Supported versions table (populate from package version if detectable)
• Vulnerability reporting instructions (email-based, not public issues)
• Response timeline expectations

4e. CODEOWNERS

Scan the top-level directory structure and generate a CODEOWNERS file. Map directories to the repo owner by default. Add comments explaining how to customize.

4f. .editorconfig

Generate settings appropriate to the detected project type:

• Indent style and size
• End-of-line character
• Trim trailing whitespace
• Insert final newline
• Charset (utf-8)

4g. .github/ISSUE_TEMPLATE/bug-report.yml

Generate a YAML form-based bug report template with fields: description, steps to reproduce, expected behavior, actual behavior, environment, and optional screenshots. See REFERENCE.md for YAML form spec.

4h. .github/ISSUE_TEMPLATE/feature-request.yml

Generate a YAML form-based feature request template with fields: problem statement, proposed solution, alternatives considered, and additional context.

4i. .github/pull_request_template.md

Generate a PR template with sections: summary of changes, type of change (checkboxes), testing performed, and checklist.

4j. .github/workflows/ci.yml

Generate a CI skeleton for GitHub Actions (unless --ci none). Include:

• Trigger on push to main and pull requests
• Language-appropriate setup step
• Lint step (ESLint, ruff, clippy, golangci-lint)
• Test step (language-appropriate test runner)
• Placeholder comments for additional steps

4k. Optional: Safety Files (when --public)

When --public is passed, also generate:

• .public-repo — Empty marker file indicating the repo is public
• .pii-allowlist — One regex per line; starts with a comment header explaining usage
• .commit-msg-blocklist — One term per line; starts with a comment header and common defaults

Step 5: Present Plan

Before writing any files, present the full list of files to be created with a one-line description of each. Show which files were skipped due to conflicts. Ask the user to confirm before proceeding.

Step 6: Write Files

Write all confirmed files. Report each file as it is written.

Step 7: Summary

Print a summary table:

• Files created (with paths)
• Files skipped (with reason)
• Suggested next steps (e.g., review CODEOWNERS, customize CONTRIBUTING.md, add secrets to CI)

Key Principles

1. Never overwrite existing files. Always scan first, flag conflicts, and ask.
2. Always ask before writing. Present the plan and get explicit confirmation.
3. Language-appropriate defaults. Detect the project type and tailor every template.
4. Minimal but complete. Generate the standard set every well-maintained repo needs, nothing more.
5. Composable. Each file stands alone. Re-run the skill later to add missing files without disrupting existing ones.

References

• REFERENCE.md — License comparison, .gitignore patterns, YAML template spec, CI skeletons, CODEOWNERS syntax, .editorconfig settings, SECURITY.md and CONTRIBUTING.md templates
• EXAMPLES.md — Worked examples for Node.js, Python, and public repo scaffolding