architecting-solutions
by zhaono1architecting-solutions is a Claude Code skill for technical design, migration planning, and Requirements Planning. It clarifies requirements, analyzes codebase constraints, compares trade-offs, and writes a PRD-style design to your project's docs/ folder.
This skill scores 68/100, which means it is acceptable to list for directory users, but they should expect a document-driven workflow with some ambiguity rather than a tightly operationalized architecture assistant. The repository gives clear trigger phrases, a structured process, and a concrete output location, so an agent can likely invoke it correctly and produce usable design artifacts with less guesswork than a generic prompt.
- Strong triggerability: SKILL.md explicitly names when to use it and when to defer to `prd-planner`, including example phrases and a PRD-specific boundary.
- Operationally useful workflow: the skill describes requirement clarification, context analysis, solution design, and generating markdown output in `docs/`.
- Substantial written guidance: long SKILL.md with workflow, constraints, checklists, and examples gives more reusable structure than a bare prompt template.
- Purpose drift in the docs: the title says architecture design, but SKILL.md also says it creates detailed PRDs, which may confuse install decisions and agent behavior.
- Limited executable support: no scripts, references, rules, or install command in SKILL.md, so output quality depends heavily on the agent interpreting prose correctly.
Overview of architecting-solutions skill
What architecting-solutions does
The architecting-solutions skill is a structured architecture-and-solution-design workflow for Claude Code. It is meant for turning a rough request like “design a billing system” or “plan a migration” into a more complete technical design with clarified requirements, trade-offs, and a written output in your project’s docs/ folder.
Who should use architecting-solutions
This skill is best for engineers, tech leads, staff engineers, and AI-assisted builders who need more than a generic brainstorming answer. It fits work such as system design, migration planning, refactors, feature architecture, and Requirements Planning that needs explicit constraints and a documented recommendation.
The real job-to-be-done
Users typically want one of three outcomes:
- turn an ambiguous request into a concrete technical plan,
- compare solution options with trade-offs,
- leave behind a reusable PRD-style architecture document for implementation.
That makes architecting-solutions more useful than a one-shot “design this system” prompt when the project context matters.
Key differentiators from an ordinary prompt
The main value of architecting-solutions is its workflow discipline:
- it starts by clarifying requirements,
- it analyzes existing codebase patterns and constraints,
- it produces a documented solution rather than only chat output,
- it explicitly writes the result to
docs/.
A notable nuance: the repository description says not to use it for PRD-specific work if the request explicitly mentions PRD, but the skill itself also generates PRD-style output. In practice, the fit is strongest for technical design and Requirements Planning with implementation context, not pure product discovery.
When architecting-solutions is a strong fit
Use architecting-solutions when you need:
- architecture design for a new feature or subsystem,
- migration or refactor planning,
- a technical design for an existing codebase,
- solution options with trade-off analysis,
architecting-solutions for Requirements Planningwhere technical scope and constraints matter.
When to skip this skill
Do not reach for architecting-solutions if you only need:
- a lightweight brainstorm,
- a purely product-facing PRD with no architecture depth,
- a bug fix plan,
- code generation without design work,
- a decision that depends mostly on business prioritization rather than technical constraints.
How to Use architecting-solutions skill
Install context and repository path
This skill lives at skills/architecting-solutions inside zhaono1/agent-playbook.
A practical install command is:
npx skills add https://github.com/zhaono1/agent-playbook --skill architecting-solutions
The skill documentation also notes a typical installed path of:
~/.claude/skills/architecting-solutions/
Read these files first
For a fast evaluation, read files in this order:
skills/architecting-solutions/SKILL.mdskills/architecting-solutions/README.md
SKILL.md carries most of the operational detail: trigger conditions, workflow, allowed tools, and the requirement to write output into docs/.
How architecting-solutions is triggered in practice
The repository examples are direct, plain-English requests such as:
- “Design solution for a new billing system”
- “Provide an architecture design for multi-tenant analytics”
- “Technical design for a data migration plan”
That means architecting-solutions usage is prompt-driven rather than command-heavy. The trigger is the intent: solution design, architecture design, technical design, migration planning, or feature-level technical planning.
Inputs that materially improve output quality
The skill performs much better when you provide:
- system goal,
- users or workloads,
- hard constraints,
- existing stack,
- non-functional requirements,
- delivery boundaries.
Good input example:
“Use architecting-solutions to design a multi-tenant analytics ingestion service for our Node.js/Postgres stack. We ingest 50M events/day, need tenant isolation, 99.9% uptime, GDPR deletion support, and rollout in two phases without breaking current APIs.”
Why this works: it gives scale, stack, constraints, reliability targets, and rollout limits, which are exactly the details that change architecture decisions.
Turn a vague request into a strong prompt
Weak:
“Design an analytics system.”
Stronger:
“Use architecting-solutions to propose 2 architecture options for a multi-tenant analytics platform in our existing Python + Kafka + ClickHouse environment. Include ingestion, storage, query path, tenant isolation, observability, and migration risk. Recommend one option and write the final design to docs/analytics-architecture.md.”
The stronger version improves option quality, comparison depth, and output format.
Suggested workflow for real projects
A practical architecting-solutions guide looks like this:
- start with the problem statement,
- let the skill ask clarification questions,
- point it at the relevant repo areas,
- force explicit trade-offs between 2–3 options,
- ask for a recommendation,
- have it write the final markdown into
docs/, - review gaps before implementation starts.
This is especially useful for Requirements Planning because it separates discovery, constraints, and final design instead of collapsing everything into one answer.
What the skill is opinionated about
The strongest repository-level opinion is output location: write the final PRD-style document to {PROJECT_ROOT}/docs/, not hidden files or temporary planning notes. If your team stores design docs elsewhere, specify that early so the agent does not default to the documented path.
Best prompts for codebase-aware design
If you already have a repository open, say what to inspect:
“Use architecting-solutions for Requirements Planning on our auth overhaul. Review services/auth/, docs/current-architecture.md, and infra/terraform/ first. Match existing deployment patterns unless there is a strong reason not to.”
This matters because the skill is explicitly designed to analyze context and existing patterns before proposing a solution.
Expected output shape
Based on the workflow, expect the skill to produce:
- requirement clarification,
- context and constraint analysis,
- proposed architecture,
- trade-offs,
- implementation-oriented documentation in markdown.
If you need a lighter answer, say so. Otherwise the default shape is documentation-first rather than quick chat advice.
Common adoption blocker
The biggest blocker is unclear scope. If you ask for architecture without naming constraints, the output can become generic. Before judging the skill, test it with a request that includes concrete scale, system boundaries, and at least one hard trade-off such as cost vs speed, consistency vs latency, or reuse vs rewrite.
architecting-solutions skill FAQ
Is architecting-solutions good for beginners?
Yes, if beginners already know the system they are working in. The workflow helps by forcing clarification and structured thinking. But beginners may still struggle to validate trade-offs, so the skill works best with human review from a more experienced engineer.
Is this a PRD skill or an architecture skill?
Operationally, it is both, but architecture comes first. The repository metadata positions architecting-solutions as a technical solution and architecture skill, while the workflow writes a PRD-style markdown artifact. Use it when the document is driven by technical design, not when you need a purely product-management PRD.
How is architecting-solutions different from a normal “design this” prompt?
A normal prompt often returns a polished but context-light answer. architecting-solutions skill is better when you want a repeatable process: clarify requirements, inspect the codebase, compare options, and produce a saved design document.
Does architecting-solutions install extra tooling?
No special helper scripts or resource folders are surfaced here. architecting-solutions install is mainly about adding the skill from the agent-playbook repository and then invoking it through Claude Code with the right prompt and repository context.
Can I use architecting-solutions for Requirements Planning?
Yes. architecting-solutions for Requirements Planning is a strong fit when requirements depend on technical constraints, migration realities, or architecture choices. It is less suitable for early-stage market validation or purely business-side requirement drafting.
When should I not use architecting-solutions?
Skip it when you need:
- a product strategy memo,
- a short implementation checklist,
- debugging help,
- a code-only answer,
- a PRD with no architecture analysis.
How to Improve architecting-solutions skill
Give stronger constraints, not broader goals
The best way to improve architecting-solutions results is to replace broad asks with design-driving constraints:
- traffic scale,
- latency targets,
- compliance needs,
- deployment environment,
- backward compatibility,
- cost limits,
- deadlines.
These inputs produce sharper trade-offs than generic goals like “scalable” or “robust.”
Ask for options before asking for the answer
If the first response feels narrow, request:
“Give me 2–3 viable architectures first, with trade-offs and failure risks, before writing the final recommendation.”
This prevents the skill from converging too early on a single pattern.
Point the skill to the right code and docs
A common failure mode is architecture that ignores local conventions. Improve output by naming exact paths:
services/apps/docs/infra/- current ADRs or design docs
For an existing system, this often matters more than adding more prose to the prompt.
Make the output artifact explicit
If you want a reusable document, specify the filename and audience:
“Write the final design to docs/payment-migration.md for backend engineers and reviewers.”
That aligns with the skill’s documented behavior and reduces ambiguity around format and depth.
Fix generic first drafts with targeted follow-ups
After the first pass, do not ask “make it better.” Ask for specific upgrades:
- add operational risks,
- compare migration strategies,
- include rollback plan,
- show data model implications,
- map dependencies by team,
- call out unknowns needing validation.
Targeted iteration improves the document faster than re-running the whole prompt.
Watch for the biggest failure modes
The main quality risks with architecting-solutions are:
- under-specified constraints,
- architecture detached from the actual codebase,
- overconfident recommendations with weak trade-off analysis,
- PRD-style output that is too broad for implementation planning.
You can usually correct all four by giving repo paths, hard constraints, and a required comparison section.
Improve architecting-solutions with review loops
The best workflow is two-pass:
- use
architecting-solutionsto produce the initial design, - review it for missing constraints and challenge the recommendation.
Ask follow-ups such as:
- “What assumptions would most likely break this design?”
- “What is the cheapest acceptable version?”
- “What changes if we optimize for 3-month delivery instead of long-term scale?”
That turns the skill from a document generator into a practical design review assistant.