Transform Claude Code (or any AI coding assistant) into a specialized architect agent that plans, delegates work to code agents, grades implementations, and maintains quality through iterative improvement.
Plan -> Delegate -> Grade -> Iterate -> Learn
- Plan: Create detailed, structured instructions for code agents
- Delegate: Send instructions to code agents for implementation
- Grade: Evaluate completed work against objective rubrics (target: 95% or higher)
- Iterate: Guide improvements until quality threshold met
- Learn: Update code agent memory with successful patterns
The recommended way to install this skill across different AI coding agents is using the skilz universal installer. This skill supports the Agent Skill Standard, which means it works with 14+ coding agents including Claude Code, OpenAI Codex, Cursor, and Gemini.
pip install skilzYou can use either -g or --git with HTTPS or SSH URLs:
# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/architect-agent
# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/architect-agent.gitInstall to user home (available in all projects):
skilz install -g https://github.com/SpillwaveSolutions/architect-agentInstall to current project only:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --projectInstall for OpenCode:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent opencodeProject-level install:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --project --agent opencodeProject-level install for Gemini:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent geminiInstall for OpenAI Codex:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --agent codexProject-level install:
skilz install -g https://github.com/SpillwaveSolutions/architect-agent --project --agent codex# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent
# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --project
# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent opencode
# OpenCode project level
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent opencode --project
# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent codex
# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent codex --project
# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_architect-agent/architect-agent --agent geminiSee skill Listing for installation details for 14+ different coding agents.
Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more. For the full list of supported platforms, visit:
SkillzWave - Largest Agentic Marketplace for AI Agent Skills | SpillWave - Leaders in AI Agent Development
Clone directly into your Claude Code skills directory:
git clone https://github.com/SpillwaveSolutions/architect-agent.git ~/.claude/skills/architect-agent- Objective Grading - 6-category rubric (100 points total)
- Iterative Improvement - Repeat until 95% or higher quality achieved
- Memory Management - Code agents learn from successes and failures
- Progressive Disclosure - 3-level architecture minimizes context usage
- Cross-Workspace Collaboration - Architect to code agent workflows
- Template Automation - Setup workspaces in less than 5 minutes
- Dual-Mode Logging - Works with Claude Code and OpenCode
- Comprehensive Protocols - 29 reference files covering all scenarios
# Navigate to templates
cd ~/.claude/skills/architect-agent/templates/
# Create code agent workspace
./setup-workspace.sh code-agent ~/projects/my-code-agent
# Create architect workspace (optional)
./setup-workspace.sh architect ~/projects/my-architect \
--code-agent-path ~/projects/my-code-agent
# Verify installation
cd ~/projects/my-code-agent
~/projects/my-architect/verify-workspace.shComplete in less than 5 minutes! See references/installation.md for details.
Use skill triggers for step-by-step guidance:
- "This is a new architect agent, help me set it up"
- "Write instructions for code agent"
- "Grade the code agent's work"
User: "write instructions for implementing JWT authentication"
Architect Agent:
-> Creates human-readable summary (human/*.md)
-> Creates detailed technical instructions (instructions/*.md)
-> Includes logging requirements, testing protocol, success criteria
Architect: "send instructions to code agent"
-> Copies to code-agent/debugging/instructions/<uuid>.md
-> Generates 10-point summary
Code Agent: "run instructions"
-> Implements features
-> Creates detailed logs
-> Signals: "instructions completed, ready for grading"
Architect: "grade the work"
-> Evaluates against rubric
-> If 95% or higher: Success! Files deleted
-> If less than 95%: Creates improvement instruction
Code Agent: "improve your score" (if needed)
-> Implements targeted fixes
-> Repeat until 95% or higher
Level 1: Metadata (~100 words)
- Always in context
- Skill name, description, triggers
Level 2: SKILL.md (less than 5k words)
- Core workflows and protocols
- Quick reference checklists
- Links to detailed references
Level 3: References (unlimited)
- 29 detailed protocol files
- Loaded only when needed
- Keeps context window lean
Architect Workspace Code Agent Workspace
(YOU work here) (THEY work there)
=================== ====================
instructions/ src/
instruct-*.md <- YOU code files <- THEY
human/ tests/
human-*.md <- YOU test files <- THEY
grades/ debugging/
grade-*.md <- YOU logs/ <- THEY
ticket/ instructions/ (temporary)
analysis/ CLAUDE.md (memory)
CLAUDE.md AGENTS.md (protocols)
- SPEC.md - Project specification (purpose, scope, architecture)
- SKILL.md - Main skill documentation (all triggers and workflows)
- references/README.md - Index of all 29 reference files
- CONTRIBUTING.md - Git workflow and contribution guidelines
Setup and Installation:
- references/installation.md - Complete installation guide
- references/upgrade.md - Migration from v1.0/v2.0 to v3.0+
- references/quick_start.md - 5-minute getting started
Core Protocols:
- references/logging_protocol.md - Real-time logging with tee
- references/testing_protocol.md - Progressive testing schedule
- references/grading_rubrics.md - 6-category grading system
- references/agent_specialization.md - Right agent for the job
Advanced:
- references/instruction_grading_workflow.md - Iterative improvement cycle
- references/permissions_setup_protocol.md - Cross-workspace permissions
OpenCode Integration:
- references/opencode_integration_quickstart.md - Dual-mode setup
- references/claude_vs_opencode_comparison.md - Feature comparison
| Category | Points | Key Criteria |
|---|---|---|
| Completeness | 25 | All requirements met, success criteria checked |
| Code Quality | 20 | Best practices, maintainability, correctness |
| Testing and Verification | 20 | Coverage 60% or higher, all actions verified |
| Documentation | 15 | Complete logs, change docs, inline comments |
| Resilience and Adaptability | 10 | Recovery from errors, smart workarounds |
| Logging and Traceability | 10 | Real-time logs, timestamps, clear decisions |
Target: 95 points or higher for successful completion
Automatic Grade Caps:
- No unit tests run: Max D (65%)
- Tests fail: F (50%) - UNACCEPTABLE
- Coverage less than 60%: Max C- (70%)
- v4.0 (Current): Comprehensive reorganization, all references linked, seamless UX
- v3.0: Hooks fix (settings.json), automated templates, verification scripts
- v2.0: Hybrid logging, improved protocols
- v1.0: Initial release (manual logging)
See CONTRIBUTING.md for complete workflow.
Quick Summary:
- Create feature/fix branch (
feat/<description>orfix/<description>) - Create GitHub issue FIRST
- Commit with issue reference (
Fixes #<number>) - Create pull request with full description
- Never commit directly to main
Documentation:
- Browse references/ for detailed protocols
- Read SPEC.md for project architecture
- Check SKILL.md for complete usage guide
Getting Help:
- Review references/get_unstuck_protocol.md for troubleshooting
- Check references/quick_start.md for common questions
- Create an issue for bugs or feature requests
MIT License - Modify and adapt for your workflow and team needs.
Last Updated: 2025-12-29 Version: 4.0
