github-repo-architect git:20260514.3080b38A

Immutable. This exact content never changes and is served at /api/v1/blob/2743bfe614c09d8c.

---
name: github-repo-architect
description: Convert a repository idea into a complete GitHub repository architecture. Always trigger immediately when the user's message starts with "repo", "gra", or "architect repo". Also trigger on "build a repo structure", "design a GitHub repo", "scaffold this repository", "create repository architecture", "turn this idea into a repo", or any request to generate README, folder layout, prompts, GitHub Actions CI, issue templates, pull request templates, or starter project structure for a new repository.
---

# GitHub Repo Architect Skill

Turn a rough project idea into a complete GitHub repository plan that can be implemented directly. Produce the repository structure, README, prompts, CI pipeline, and starter files that fit the project.

## Primary Triggers

**`repo`**, **`gra`**, or **`architect repo`** — Provide the idea after the trigger and generate the repository architecture immediately.

Other triggers: "build a repo structure", "design a GitHub repo", "scaffold this repository", "create repository architecture", "turn this idea into a repo"

```text
repo [project idea, target language, or rough requirements]
gra [GitHub repo concept]
architect repo [existing notes or spec]
```

## Do Not Use When

- The user wants to improve an **existing repo** that already has structure — use a code review or audit approach instead.
- The user only needs a **README written** for a known repo layout — use the `github-readme` skill instead.
- The user has **no project idea** and wants a generic starter template with no specifics — ask for a concrete idea before proceeding.
- The request is for **a private or sensitive system** (internal corporate infra, credential vaults, personal data stores) and no security context has been provided — gather security requirements first.

## Step 1 — Identify Project Type

Classify the idea before writing files. Choose the closest type and adapt the output.

| Type | Examples | Architecture Focus |
|---|---|---|
| Claude or Codex skill | Content writer, repo architect, automation helper | `skill.md`, README, packaging notes, examples |
| CLI tool | PowerShell module, Python utility, Node script | commands, config, tests, release workflow |
| API service | FastAPI, Express, Flask, webhook receiver | routes, auth, OpenAPI, tests, deploy path |
| Web app | React, Next.js, static dashboard | app structure, components, env vars, build workflow |
| MCP server | Home Assistant MCP, Pi-hole MCP | tool definitions, server entrypoint, config, tests |
| Automation repo | Playwright scraper, scheduled task, n8n helper | workflows, secrets, logs, retries, docs |
| Data project | ETL, analysis notebook, report generator | datasets, schemas, reproducibility, outputs |
| Infrastructure repo | Docker, Proxmox, Terraform, Ansible | inventory, variables, validation, rollback notes |

If the type is unclear, pick the safest minimal architecture and state the assumption in one line.

## Step 2 — Extract Requirements

Pull these details from the user's message:

- Repo name or working title
- Goal and target user
- Language or framework
- Runtime environment
- Inputs and outputs
- External services, APIs, secrets, or credentials
- Required commands
- Deployment target
- Test expectations
- License preference

If a key detail is missing, make a practical assumption. Ask a question only when the missing detail changes the whole architecture.

## Step 3 — Generate The Repository Blueprint

Return a complete blueprint in this order:

1. **Repository name**
2. **One sentence purpose**
3. **Assumptions**
4. **Folder layout**
5. **Generated files**
6. **README.md**
7. **Development prompts**
8. **GitHub Actions CI**
9. **Setup commands**
10. **Next implementation tasks**

For code or automation repos, include starter file contents when the user asks for a scaffold or when the idea is specific enough to generate useful files. For broad planning requests, provide filenames and concise descriptions instead of long boilerplate.

## Folder Layout Rules

Use an annotated tree. Keep the structure lean and useful.

```text
RepoName/
|-- README.md                  # Project overview and usage
|-- .github/
|   |-- workflows/
|   |   |-- ci.yml             # Test and lint workflow
|   |-- ISSUE_TEMPLATE/
|   |   |-- bug_report.md      # Bug report template
|   |   |-- feature_request.md # Feature request template
|   |-- pull_request_template.md
|-- src/                       # Main source code
|-- tests/                     # Automated tests
|-- docs/                      # Architecture and usage notes
```

Adapt folders to the project. Do not add empty complexity. Avoid including Docker, Terraform, or release automation unless the project calls for it.

## README Requirements

Generate a complete README tailored to the repo. Include only sections that fit.

Core sections:

- `# [Repo Name]`
- One sentence description
- `## Overview`
- `## What This Does`
- `## Repository Structure`
- `## Prerequisites`
- `## Setup`
- `## Usage`
- `## Testing`
- `## Configuration`
- `## Security Notes`
- `## License`

Use tables for structured configuration, commands, modules, or environment variables.

## Development Prompts

Include prompts that help the user continue building the repo with Claude or Codex.

Prompt set:

- **Implementation prompt** — build the first working version from the scaffold
- **Test prompt** — add or improve automated tests
- **Review prompt** — inspect for bugs, missing docs, and security issues
- **Release prompt** — prepare tags, changelog, and release notes when relevant

Prompts must be specific to the generated repository. Do not write generic prompts that could apply to any project.

## GitHub Actions CI

Generate `.github/workflows/ci.yml` for the chosen stack.

Minimum workflow:

- Runs on pull requests and pushes to the default branch
- Checks out the repo
- Sets up the language runtime
- Installs dependencies
- Runs linting when a lint command exists
- Runs tests

Use conservative defaults:

| Stack | CI Defaults |
|---|---|
| Python | `actions/setup-python`, install from `requirements.txt` or `pyproject.toml`, run `pytest` |
| Node | `actions/setup-node`, `npm ci`, `npm test`, `npm run lint` if present |
| PowerShell | `pwsh`, `Invoke-ScriptAnalyzer` if configured, Pester tests |
| .NET | `actions/setup-dotnet`, `dotnet restore`, `dotnet test` |
| Docker | `docker build` and optional compose validation |
| Claude skill | package validation, archive creation, markdown checks |

If no stack is clear, create a placeholder CI with markdown checks and TODO comments.

## Issue And PR Templates

Include templates when generating a full repo scaffold.

Bug report fields:

- Problem
- Steps to reproduce
- Expected result
- Actual result
- Environment

Feature request fields:

- Use case
- Proposed behavior
- Inputs
- Outputs
- Notes

Pull request template fields:

- Summary
- Changes
- Tests
- Risk
- Checklist

## Voice And Formatting Rules

Apply Mick's repository voice to human facing prose:

- No emojis
- No motivational sign offs
- No AI sounding language: "journey", "transformative", "game-changer", "leverage", "showcase", "utilize", "diving deep", "I'm excited to share", "The takeaway here is..."
- First person only when the repository is personal or intentionally written from Mick's perspective
- Direct, conversational, short sentences
- Lead with concrete details
- Use exact commands and file paths

Technical syntax is allowed to use hyphens, quotation marks, YAML punctuation, package names, flags, and filenames when required.

## Output Guardrails

- Do not produce a generic template when project details are available.
- Do not invent secrets, API keys, URLs, or package names.
- Mark uncertain commands as assumptions.
- Keep generated CI runnable for the selected stack.
- Include security notes for any repo that handles secrets, credentials, personal data, trading data, scraping, or automation against logged in services.
- Keep the initial architecture small enough for one person to build.

## Validation Checklist

Run these checks before delivering any generated blueprint:

- Generated folder tree matches the stated project type from the type table.
- README includes all required sections for the project — no placeholder headings with no content.
- CI workflow targets the correct runtime and includes a working test or lint step, not just a checkout.
- Development prompts reference actual files and folder names from the generated repo, not generic placeholders.
- Security notes are present whenever the project involves API keys, credentials, personal data, scraping, or automation against authenticated services.
- No invented package names, service URLs, or environment variable values appear in generated files.
- Setup commands are runnable as written for the stated language and OS.
- Architecture fits one person building from scratch — no unnecessary layers, services, or abstractions.
- If type was unclear and an assumption was made, that assumption is stated in the output.

## Help And Examples

If the user is not sure how to use this skill, asks what it needs, or asks for examples:

- Explain in plain language what this skill can do.
- Tell the user the minimum input needed for a useful first pass.
- Show the example prompts below.
- Offer the fastest next prompt the user can send.

Minimum useful input:

- The project idea, target stack, and any must-have repo components.

Example prompts:

- `Use github-repo-architect to turn this project idea into a complete repo layout with docs and workflows.`
- `Design the structure for a PowerShell and Python automation repo with clear module boundaries.`
- `Show me how to ask this skill for a repository architecture plan with folders and starter files.`