agent-architecture-planner
Use when designing an autonomous agent, planning agent architecture, building a scheduled automation, or creating a Claude Code agent workflow. Triggers: 'design an agent', 'build an automation', 'agent architecture', 'automate this workflow', 'create a scheduled agent', 'shell script agent'.
npx skills add majiayu000/claude-skill-registry --skill agent-architecture-planner --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Design autonomous agents using the "Shell Orchestrates, Claude Thinks" pattern. This skill takes a workflow description, selects the right architecture pattern, and produces a complete agent package: shell wrapper, system prompt, config, scheduling setup, and cost estimate.
The core principle is that the shell handles everything deterministic (API calls, file I/O, scheduling, budget tracking), and Claude handles everything that requires judgment (scoring, filtering, writing, categorizing).
How it works
Tools Used
- Read: Check for existing agent docs, load reference files
- Write: Output all agent architecture files
- Bash: Make shell scripts executable, verify directory structure
- Glob: Check for existing agents to avoid naming conflicts
Methodology
Follows a strict 4-step process:
- Workflow Discovery: Interactive questions are presented to the user all at once; user answers, or inline text is provided. If the initial task is vague, follow-up questions are asked. Only proceed after user responses.
- Architecture Pattern Selection: Based on answers, select one of four patterns (Simple Pipeline, Dual-Layer Pipeline, Multi-Agent Decomposition, Feedback Loop) and justify. Present one recommended pattern unless two are close.
- Component Design: For the chosen pattern, design four components in sequence without writing files yet:
- 3A Shell Wrapper Design: outlines environment setup, gate checks, data acquisition, preprocessing, Claude invocation, budget tracking, logging, cleanup, and error handling. Presented as a bulleted outline; user can adjust sections.
- 3B System Prompt Design: outlines a structured system prompt with sections (Role Definition, Context, Task Steps, Output Format, Rules, Example Output). Presents the outline for user confirmation.
- 3C Config File Design: designs a YAML config file with sections for agent, data_sources, budget, output, filters, schedule. Proposes values and asks for adjustments.
- 3D Scheduling Design: provides platform-specific scheduling templates (macOS launchd plist and Linux cron) including a gate mechanism that preserves minimum gaps between runs.
- Cost Estimation: computes token-based estimates and presents a cost-per-run and monthly projection table (token estimation and Claude pricing) as a draft.
When to use it
Triggers include prompts like design an agent, build an automation, agent architecture, automate this workflow, create a scheduled agent, shell script agent.
What it can touch
The skill references tools: Read, Write, Bash, Glob, and Claude Code for actual agent creation. It specifies that the system prompt and architecture files are produced, and that a shell wrapper uses Bash and can invoke Claude.
Caveats
License: MIT. Version: 1.0.0. Skills depend on user-provided workflow discovery and confirmation before generating the architecture files. Output is a design blueprint and scaffolding description; actual file creation is deferred until user confirmation.
# Agent Architecture Planner Design autonomous agents using the "Shell Orchestrates, Claude Thinks" pattern. This skill takes a workflow description, selects the right architecture pattern, and produces a complete agent package: shell wrapper, system prompt, config, scheduling setup, and cost estimate. The core principle: **the shell handles everything deterministic** (API calls, file I/O, scheduling, budget tracking), and **Claude handles everything that requires judgment** (scoring, filtering, writing, categorizing). This separation makes agents cheaper, more reliable, and easier to debug. --- ## Tools Used | Tool | Purpose | |---|---| | `Read` | Check for existing agent docs, load reference files | | `Write` | Output all agent architecture files | | `Bash` | Make shell scripts executable, verify directory structure | | `Glob` | Check for existing agents to avoid naming conflicts | --- ## Methodology Follow these steps in order. Do not skip steps. Do not produce output files before completing the discovery interview and confirming the architecture with the user. --- ### Step 1 — Workflow Discovery (Interactive) Present these questions to the user **all at once** in a numbered lis
- Tools Used
- Methodology
- Step 1 — Workflow Discovery (Interactive)
- Step 2 — Architecture Pattern Selection
- Step 3 — Component Design
- Step 4 — Cost Estimation
- Step 5 — Data Optimization Tips
- Step 6 — Output
- Post-Output Actions
- Rules (Non-Negotiable)
if [ -f "$GATE_FILE" ]; then
if [ "$hours_since" -lt "$MIN_HOURS_BETWEEN_RUNS" ]; then
echo "Gate check: only ${hours_since}h since last run (min: ${MIN_HOURS_BETWEEN_RUNS}h). Skipping."
exit 0
fi
After each API call, log the cost
Between batches, check cumulative spend against the daily cap
Correct — works with any prompt size
cat "$PROMPT_FILE" | claude -p
Incorrect — breaks when prompt exceeds shell ARG_MAX (~262KB on most systems)What does the agent-architecture-planner skill do?
Use when designing an autonomous agent, planning agent architecture, building a scheduled automation, or creating a Claude Code agent workflow. Triggers: 'design an agent', 'build an automation', 'agent architecture', 'automate this workflow', 'create a scheduled agent', 'shell script agent'.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill agent-architecture-planner --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.