repo-architect

Bootstraps and validates agentic project structures for GitHub Copilot (VS Code) and OpenCode CLI workflows. Run after `opencode /init` or VS Code Copilot initialization to scaffold proper folder hierarchies, instructions, agents, skills, and prompts.

13 stars

bytae0y

View on GitHub Installation ↓

Best use case

repo-architect is best used when you need a repeatable AI agent workflow instead of a one-off prompt.

Teams using repo-architect should expect a more consistent output, faster repeated execution, less prompt rewriting.

When to use this skill

You want a reusable workflow that can be run more than once with consistent structure.

When not to use this skill

You only need a quick one-off answer and do not need a reusable workflow.
You cannot install or maintain the underlying files, dependencies, or repository context.

Installation

Claude Code / Cursor / Codex

$curl -o ~/.claude/skills/repo-architect/SKILL.md --create-dirs "https://raw.githubusercontent.com/tae0y/python-project-template/main/.claude/skills.nouse/repo-architect/SKILL.md"

Manual Installation

Download SKILL.md from GitHub
Place it in .claude/skills/repo-architect/SKILL.md inside your project
Restart your AI agent — it will auto-discover the skill

How repo-architect Compares

Feature / Agent	repo-architect	Standard Approach
Platform Support	Not specified	Limited / Varies
Context Awareness	High	Baseline
Installation Complexity	Unknown	N/A

Frequently Asked Questions

What does this skill do?

Where can I find the source code?

You can find the source code on GitHub using the link provided at the top of the page.

Related Guides

Best AI Skills for Claude

Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.

SKILL.md Source

# Repo Architect

Scaffold and validate agentic project structures for VS Code GitHub Copilot and/or OpenCode CLI.

## 3-Layer Architecture

```
PROJECT ROOT
├── [LAYER 1: FOUNDATION]
│   ├── .github/copilot-instructions.md   ← VS Code reads this
│   └── AGENTS.md                          ← OpenCode CLI reads this
├── [LAYER 2: SPECIALISTS]
│   ├── .github/agents/*.agent.md
│   └── .opencode/agents/*.agent.md
└── [LAYER 3: CAPABILITIES]
    ├── .github/skills/*.md
    ├── .github/prompts/*.prompt.md
    └── .github/instructions/*.instructions.md
```

## Commands

### `/bootstrap` — Full Scaffolding

1. Detect existing `.github/`, `.opencode/`, project language/framework
2. Create directory structure:
   ```
   .github/copilot-instructions.md
   .github/agents/   .github/instructions/   .github/prompts/   .github/skills/
   .opencode/opencode.json   .opencode/agents/   # if OpenCode detected
   AGENTS.md  ← symlink or custom version of copilot-instructions.md
   ```
3. Generate foundation files from templates (see [references/templates.md](references/templates.md))
4. Add starter agent, instructions, and prompt for the detected stack
5. Run `/validate` after scaffolding

### `/validate` — Structure Check

1. Check required files exist and are non-empty
2. Spot-check naming conventions (lowercase-with-hyphens, correct extensions)
3. Verify symlinks are valid (hybrid setup)
4. Report:
   ```
   ✅ Structure Valid | ⚠️ Warnings | ❌ Issues

   Foundation: ✅ copilot-instructions.md  ✅ AGENTS.md
   Agents:     ✅ reviewer.agent.md  ⚠️ architect.agent.md — missing 'model'
   Skills:     ❌ test-gen.prompt.md — missing 'description'
   ```

### `/migrate` — Migrate Existing Config

Supported sources: `.cursor/`, `.aider/`, standalone `AGENTS.md`, `.vscode/` settings → `.github/` + `.opencode/`

### `/sync` — Sync VS Code ↔ OpenCode

Update symlinks, propagate shared skill changes, validate cross-environment consistency.

### `/suggest` — Community Resources

**Requires `awesome-copilot` MCP server.** Check for `mcp_awesome-copil_*` tools first.
- If available: search for agents/instructions/prompts matching the detected stack, suggest collections, offer install links
- If not available: skip entirely; optionally inform the user to enable the MCP server

## Execution Rules

- **Detect first** — survey the project before making changes
- **Non-destructive** — never overwrite without confirmation
- **Validate after** — always run `/validate` after `/bootstrap` or `/migrate`
- **Respect existing conventions** — adapt templates to match project style

For file templates and frontmatter requirements, see [references/templates.md](references/templates.md).

## Output Format

After each command provide:
1. **Summary** — what was created/validated
2. **Next Steps** — recommended immediate actions
3. **Customization Hints** — how to tailor for specific needs

Related Skills

api-architect

from tae0y/python-project-template

API architect for designing and generating external service integration code. Use when building REST API clients, service integrations, or applying resilience patterns (circuit breaker, bulkhead, throttling, backoff). Generates fully implemented code across service/manager/resilience layers.

worklog

from tae0y/python-project-template

Update worklog files by moving tasks between todo/doing/done states. Use when recording task progress, starting new work, or marking tasks complete. Requires explicit arguments: worklog [done|doing|todo] [description].

template-proposal-review

from tae0y/python-project-template

Review proposal files in localdocs/localdocs/proposals/ and decide whether to apply them to the upstream python-project-template repository. Use when evaluating proposals generated by template-upstream, deciding which ones to accept or reject, and applying accepted ones to the template repo. Triggers on: "proposal 검토", "제안 검토", "template에 반영할지", "proposals 리뷰", "upstream 반영 결정".

template-downstream

from tae0y/python-project-template

Update .claude/, .mcp.json, and .pre-commit-config.yaml from the upstream python-project-template repository into the current project. Only files that exist upstream are updated — project-only files are never deleted. Use when pulling latest tooling, rules, hooks, or skills from the canonical template into this project. Triggers on: "템플릿 최신화", "template sync", "upstream 반영", "template 업데이트".

template-broadcast

from tae0y/python-project-template

Apply template-downstream to all registered downstream projects in bulk, one project at a time. Use when you want to push the latest .claude/, .mcp.json, or .pre-commit-config.yaml to every project at once. Triggers on: "일괄 배포", "전체 프로젝트에 내려보내기", "모든 프로젝트 업데이트", "broadcast template", "bulk sync".

tdd

from tae0y/python-project-template

Test-Driven Development workflow. Use for ALL code changes - features, bug fixes, refactoring. TDD is non-negotiable.

sparks-create

from tae0y/python-project-template

Apply the 13 thinking tools from "Sparks of Genius" (생각의 탄생) to reframe any problem through creative, cross-disciplinary lenses. Use when conventional analysis falls short, when you need a fresh creative angle, or when the problem spans multiple domains.

skill-creator

from tae0y/python-project-template

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

rethink-unblock

from tae0y/python-project-template

Break out of a stuck approach by reframing a technical problem through structured thinking frameworks. Use when blocked, going in circles, or when a fresh perspective is needed on architecture, design, or debugging.

refactoring

from tae0y/python-project-template

Refactoring assessment and patterns. Use after tests pass (GREEN phase) to assess improvement opportunities.

python-mcp-expert

from tae0y/python-project-template

Expert assistant for developing Model Context Protocol (MCP) servers in Python. Use when creating, debugging, or optimizing MCP servers with FastMCP, tools, resources, and prompts.

python-conventions

from tae0y/python-project-template

Python coding conventions and guidelines including PEP 8, type hints, docstrings, and testing standards. Automatically applied when working with Python files.