architect-agent
Coordinates planning, delegation, and evaluation across architect and code agent workspaces. Use when asked to "write instructions for code agent", "initialize architect workspace", "grade code agent work", "send instructions", or "verify code agent setup".
Best use case
architect-agent is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Coordinates planning, delegation, and evaluation across architect and code agent workspaces. Use when asked to "write instructions for code agent", "initialize architect workspace", "grade code agent work", "send instructions", or "verify code agent setup".
Teams using architect-agent 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
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/architect-agent/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How architect-agent Compares
| Feature / Agent | architect-agent | 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?
Coordinates planning, delegation, and evaluation across architect and code agent workspaces. Use when asked to "write instructions for code agent", "initialize architect workspace", "grade code agent work", "send instructions", or "verify code agent setup".
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.
SKILL.md Source
# Architect Agent Workflow Skill
Coordinate planning, delegation, and evaluation across architect and code agent workspaces.
**Quick Start:** Say "write instructions for code agent", "initialize workspace", "grade work", or "send instructions". For automated setup, see [Quick Setup](#quick-setup-template-based).
## Table of Contents
- [Intent Classification](#intent-classification)
- [Decision Tree](#decision-tree)
- [Resource Loading Policy](#resource-loading-policy)
- [Critical Protocol: File Locations](#critical-protocol-file-locations)
- [Quick Setup](#quick-setup-template-based)
- [DO NOT Trigger For](#do-not-trigger-for)
- [Reference Directory](#reference-directory)
- [Guides Directory](#guides-directory)
## Intent Classification
Route requests based on user intent:
| Intent | Trigger Phrases | Action |
|--------|-----------------|--------|
| **Create Instructions** | "write instructions", "create instructions", "delegate to code agent" | → Load `guides/workflows/create-instructions.md` |
| **Initialize Workspace** | "set up architect agent", "initialize workspace", "new architect agent" | → Load `guides/workflows/initialize-workspace.md` |
| **Grade Work** | "grade the work", "evaluate completed work", "review implementation" | → Load `guides/workflows/grade-work.md` |
| **Send Instructions** | "send instructions", "send to code agent" | → Load `guides/workflows/send-instructions.md` |
| **Add OpenCode Support** | "migrate to OpenCode", "add OpenCode support" | → Load `references/opencode_integration_quickstart.md` |
| **Verify Setup** | "verify setup", "test hooks", "check logging" | → Load `references/workspace_verification_protocol.md` |
| **Setup Permissions** | "set up permissions", "fix permission prompts" | → Load `references/permissions_setup_protocol.md` |
| **Upgrade Workspace** | "upgrade workspace", "migrate to v3.0" | → Load `references/upgrade.md` |
## Decision Tree
| User Intent | Pre-condition | Action |
|-------------|---------------|--------|
| "write/create instructions", "delegate" | `instructions/` exists | Load `guides/workflows/create-instructions.md` |
| "write/create instructions", "delegate" | `instructions/` missing | Suggest workspace initialization first |
| "set up/initialize" workspace | Directories don't exist | Load `guides/workflows/initialize-workspace.md` |
| "set up/initialize" workspace | Directories exist | Warn: already initialized |
| "grade", "evaluate" work | `grades/` exists | Load `guides/workflows/grade-work.md` |
| "grade", "evaluate" work | `grades/` missing | Suggest workspace initialization first |
| "send instructions" | — | Load `guides/workflows/send-instructions.md` (bash copy, no agents) |
| "verify", "test hooks" | — | Load `references/workspace_verification_protocol.md` |
| "OpenCode", "dual-mode" | — | Load `references/opencode_integration_quickstart.md` |
| "permissions" | — | Load `references/permissions_setup_protocol.md` |
| "upgrade", "migrate" | — | Load `references/upgrade.md` |
## Resource Loading Policy
**Load ONLY when needed:**
- Workflow guides: When intent is classified
- Reference docs: When user needs detailed protocol
- Templates: When creating workspace or files
- Never load all references "just in case"
**Core Resources by Intent:**
| Intent | Primary Resource | Supporting Resources |
|--------|-----------------|---------------------|
| Create Instructions | `guides/workflows/create-instructions.md` | `references/instruction_structure.md`, `references/human_instruction_structure.md`, `references/file_naming.md` |
| Initialize Workspace | `guides/workflows/initialize-workspace.md` | `references/workspace_setup_complete.md` |
| Grade Work | `guides/workflows/grade-work.md` | `references/grading_rubrics.md`, `references/decision_types.md` |
| Send Instructions | `guides/workflows/send-instructions.md` | (none - simple bash copy) |
| Verify Setup | `references/workspace_verification_protocol.md` | `references/pre_work_checklist.md` |
| Setup Permissions | `references/permissions_setup_protocol.md` | - |
| OpenCode Support | `references/opencode_integration_quickstart.md` | `references/opencode_setup_guide.md` |
## Critical Protocol: File Locations
**The architect agent operates in its own workspace, NOT the code agent workspace.**
| Artifact | Architect Writes To | Code Agent Location |
|----------|--------------------|--------------------|
| Instructions | `[ARCHITECT]/instructions/` | Reads from `debugging/instructions/` |
| Human Instructions | `[ARCHITECT]/human/` | N/A (for manual execution) |
| Grades | `[ARCHITECT]/grades/` | N/A |
| Logs | N/A | Writes to `[CODE_AGENT]/debugging/logs/` |
**Human Instructions = Executable Documentation** (not summaries!)
Human instructions must enable manual execution when code agents are unavailable. Include copy-pasteable commands, expected output, and troubleshooting. See `references/human_instruction_structure.md`.
**Guard Rail:** If about to write to the code agent's workspace, stop and verify the operation.
## Quick Setup (Template-Based)
For fastest setup, use templates:
```bash
cd ~/.claude/skills/architect-agent/templates/
# Create code agent workspace
./setup-workspace.sh code-agent ~/projects/my-code-agent
# Create architect workspace
./setup-workspace.sh architect ~/projects/my-architect \
--code-agent-path ~/projects/my-code-agent
```
**Time:** <5 minutes
**See:** `templates/README.md`
## DO NOT Trigger For
- General architecture discussions
- Brainstorming or exploration
- Reading/analyzing existing code
- Research tasks
- Any work that isn't explicit instruction creation, grading, or setup
## Reference Directory
All detailed protocols are in `references/`. Load only what is needed for the current task.
### Core References (Instruction & Grading)
| Reference | Purpose |
|-----------|---------|
| `instruction_structure.md` | Code agent instruction template |
| `human_instruction_structure.md` | Human-executable instruction template |
| `grading_rubrics.md` | 6-category grading criteria |
| `instruction_grading_workflow.md` | Full grading workflow |
| `decision_types.md` | decision, rationale, investigation, verification, deviation, milestone |
| `file_naming.md` | Timestamp and naming conventions |
### Setup & Configuration
| Reference | Purpose |
|-----------|---------|
| `installation.md` | Skill installation guide |
| `quick_start.md` | Fast-track setup |
| `workspace_setup_complete.md` | Full workspace initialization |
| `workspace_verification_protocol.md` | Verify setup is correct |
| `permissions_setup_protocol.md` | Cross-workspace permissions |
| `upgrade.md` | Upgrade to latest version |
### Logging & Debugging
| Reference | Purpose |
|-----------|---------|
| `logging_protocol.md` | Hybrid logging v2.0 |
| `hybrid_logging_protocol.md` | Detailed hybrid logging spec |
| `hook_configuration_critical.md` | Hook setup requirements |
| `hook_logger_enhancements.md` | Hook logger improvements |
| `pre_work_checklist.md` | Code agent pre-work verification |
| `get_unstuck_protocol.md` | Recovery from blockers |
| `resilience_protocol.md` | Error recovery patterns |
| `testing_protocol.md` | Progressive testing requirements |
### OpenCode Integration
| Reference | Purpose |
|-----------|---------|
| `opencode_integration_quickstart.md` | Dual-mode quick start |
| `opencode_setup_guide.md` | Full OpenCode setup |
| `opencode_migration_guide.md` | Migrate to OpenCode |
| `opencode_logging_protocol.md` | OpenCode-specific logging |
| `opencode_wrapper_setup.md` | Wrapper script setup |
| `claude_vs_opencode_comparison.md` | Feature comparison |
### Agent Configuration
| Reference | Purpose |
|-----------|---------|
| `agent_specialization.md` | Agent role configuration |
| `code_agent_claude_template.md` | CLAUDE.md template for code agents |
| `code_agent_agents_template.md` | AGENTS.md template for code agents |
### Project Management
| Reference | Purpose |
|-----------|---------|
| `git_pr_management.md` | Git and PR workflow |
| `ticket_tracking_pr_management.md` | Ticket and PR tracking |
## Guides Directory
Step-by-step workflows in `guides/workflows/`:
| Guide | Trigger |
|-------|---------|
| `create-instructions.md` | "write instructions for code agent" |
| `grade-work.md` | "grade the code agent's work" |
| `send-instructions.md` | "send instructions to code agent" |
| `initialize-workspace.md` | "set up architect agent workspace" |
### Templates
Ready-to-use workspace templates in `templates/`:
| Template | Purpose |
|----------|---------|
| `setup-workspace.sh` | Automated workspace creation script |
| `architect-workspace/` | Complete architect agent workspace template |
| `code-agent-workspace/` | Complete code agent workspace template |
**See:** `templates/README.md` for usage instructions.
---Related Skills
sdd
This skill should be used when users want guidance on Spec-Driven Development methodology using GitHub's Spec-Kit. Guide users through executable specification workflows for both new projects (greenfield) and existing codebases (brownfield). After any SDD command generates artifacts, automatically provide structured 10-point summaries with feature status tracking, enabling natural language feature management and keeping users engaged throughout the process.
mastering-hooks
Master RuleZ, the high-performance AI policy engine for development workflows. Use when asked to "install rulez", "create hooks", "debug hooks", "hook not firing", "configure context injection", "validate hooks.yaml", "PreToolUse", "PostToolUse", "block dangerous commands", "multi-platform hooks", "Gemini CLI hooks", "Copilot hooks", "OpenCode hooks", "dual-fire events", or "cross-platform rules". Covers installation, rule creation, multi-platform adapters, troubleshooting, and optimization.
using-claude-code-cli
Invoke Claude Code CLI from Python orchestrators and shell scripts. Use when asked to "spawn claude as subprocess", "automate claude cli", "run claude headless", "configure --allowedTools", "set up claude hooks", or "parallel claude invocation". Covers permissions, directory access (--add-dir), hooks, sandbox mode, and async patterns.
release-rulez
RuleZ release workflow automation. Use when asked to "release RuleZ", "create a release", "prepare release", "tag version", "hotfix release", or "publish RuleZ". Covers version management from Cargo.toml, changelog generation from conventional commits, PR creation, tagging, hotfix workflows, and GitHub Actions release monitoring.
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
project-memory
Set up and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to "set up project memory", "track our decisions", "log a bug fix", "update project memory", or "initialize memory system". Configures both CLAUDE.md and AGENTS.md to maintain memory awareness across different AI coding tools.
pr-reviewer
Comprehensive GitHub Pull Request code review skill. Use when asked to "review this PR", "code review", "review pull request", "check this PR", or when a GitHub PR URL is provided. Fetches PR metadata, diff, comments, commits, and related issues using gh CLI. Creates organized review workspace, analyzes code against industry-standard criteria, and optionally adds inline comments to the PR.
plantuml
Generate PlantUML diagrams from text descriptions and convert them to PNG/SVG images. Use when asked to "create a diagram", "generate PlantUML", "convert puml to image", "extract diagrams from markdown", or "prepare markdown for Confluence". Supports all PlantUML diagram types including UML (sequence, class, activity, state, component, deployment, use case, object, timing) and non-UML (ER diagrams, Gantt charts, JSON/YAML visualization, mindmaps, WBS, network diagrams, wireframes, and more).
mastering-typescript
Master enterprise-grade TypeScript development with type-safe patterns, modern tooling, and framework integration. This skill provides comprehensive guidance for TypeScript 5.9+, covering type system fundamentals (generics, mapped types, conditional types, satisfies operator), enterprise patterns (error handling, validation with Zod), React integration for type-safe frontends, NestJS for scalable APIs, and LangChain.js for AI applications. Use when building type-safe applications, migrating JavaScript codebases, configuring modern toolchains (Vite 7, pnpm, ESLint, Vitest), implementing advanced type patterns, or comparing TypeScript with Java/Python approaches.
mastering-python-skill
Modern Python coaching covering language foundations through advanced production patterns. Use when asked to "write Python code", "explain Python concepts", "set up a Python project", "configure Poetry or PDM", "write pytest tests", "create a FastAPI endpoint", "run uvicorn server", "configure alembic migrations", "set up logging", "process data with pandas", or "debug Python errors". Triggers on "Python best practices", "type hints", "async Python", "packaging", "virtual environments", "Pydantic validation", "dependency injection", "SQLAlchemy models".
mastering-github-cli
GitHub CLI (gh) command reference for repository search, code discovery, CI/CD monitoring, workflow authoring, and automation. Triggers on "gh" commands, "github cli", searching repos for files/directories (.skilz, .cursor, .codex, Dockerfile), monitoring GitHub Actions workflows, checking PR CI status, downloading artifacts, creating PRs/issues/repos from command line, triggering workflows, forking repos, batch operations, "write a workflow", "github actions", "CI/CD pipeline", "workflow yaml", and "matrix builds". Use for gh search, gh run, gh pr, gh issue, gh repo, gh workflow, gh api, workflow authoring, and automating GitHub operations.
mastering-git-cli
Git CLI operations, workflows, and automation for modern development (2025). Use when working with repositories, commits, branches, merging, rebasing, worktrees, submodules, or multi-repo architectures. Includes parallel agent workflow patterns, merge strategies, conflict resolution, and large repo optimization. Triggers on git commands, version control, merge conflicts, worktree setup, submodule management, repository troubleshooting, branch strategy, rebase operations, cherry-pick decisions, and CI/CD git integration.