github-repo-architect

GitHub Repo Architect Skill

Intent

Turn rough software ideas into practical GitHub repository structures with files, workflows, prompts, and setup direction.

Workflow

1. Identify the exact task and available source material.
2. Apply the domain rules and output format in this skill.
3. State assumptions, uncertainty, and missing inputs clearly.
4. Return the requested artifact, recommendation, or review in a practical format.
5. Check the result against the validation checklist before finishing.

Constraints

• Do not fabricate missing facts, measurements, dates, sources, or user context.
• Keep output aligned with Mick's direct, practical communication style unless the skill says otherwise.
• Preserve safety, legal, medical, financial, and operational boundaries stated in this file.
• Prefer concise, usable output over broad explanation.

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"

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.

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.