dev-design skill
✓ VerifiedValidates feature architecture and design documents against requirements to resolve trade-offs and ensure design completeness.
- GitHub stars
- 1,663
- Files
- 2
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the dev-design skill do?
dev-design validates feature architecture and design documents against requirements to resolve trade-offs and ensure design completeness.
Summary generated from the skill's SKILL.md.
About the dev-design skill
Validating feature architecture and design documents against requirements is what this skill enables for developers moving through the third phase of the development lifecycle. An agent should load this tool when it needs to review design docs, resolve architectural trade-offs, or ensure that every user story and constraint has corresponding design coverage. It relies on the npx ai-devkit@latest lint command to validate specific feature paths and uses mermaid diagrams to provide visual architecture clarity.
Users can employ this skill to screen for design red flags like shallow modules, leaked transport types, or scattered validation. The process involves cross-checking design docs against requirements to identify uncovered goals and resolving gaps or hidden assumptions. It prioritizes a subtract-before-add approach by consolidating redundant concepts and narrowing scope before adding new structures. Once the design is complete and all material open questions are answered, the skill produces updated design documents and summaries of requirements coverage.
What an agent can do with it
- 1Verify design completenessCheck if every goal, user story, and constraint in the requirements has corresponding design coverage.
- 2Identify architectural red flagsScan design documents for problematic patterns such as pass-through layers or leaked framework types.
- 3Resolve design trade-offsEvaluate multiple viable options for architectural decisions to reach a recommended answer.
- 4Validate feature pathsRun linting commands to ensure the design document paths are correctly identified and validated.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the dev-design skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the dev-design skill in Claude Code
~/.claude/skills/dev-design/SKILL.md
$ npx degit codeaholicguy/ai-devkit/skills/dev-design ~/.claude/skills/dev-designInstall the dev-design skill in Claude Code (project)
.claude/skills/dev-design/SKILL.md
$ npx degit codeaholicguy/ai-devkit/skills/dev-design .claude/skills/dev-designInstall the dev-design skill in Codex
~/.agents/skills/dev-design/SKILL.md
$ npx degit codeaholicguy/ai-devkit/skills/dev-design ~/.agents/skills/dev-designInstall the dev-design skill in Gemini CLI
~/.gemini/skills/dev-design/SKILL.md
$ npx degit codeaholicguy/ai-devkit/skills/dev-design ~/.gemini/skills/dev-designInstall the dev-design skill in Claude.ai
npx degit codeaholicguy/ai-devkit/skills/dev-design dev-design && zip -r dev-design.zip dev-design # claude.ai → Customize → Skills → + → Create skill → Upload a skill → dev-design.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablecodeaholicguy/ai-devkit/skills/dev-design is public and reachablegithub.com/codeaholicguy/ai-devkit/tree/HEAD/skills/dev-desi ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-09github.com/codeaholicguy/ai-devkit/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/codeaholicguy/ai-devkit/blob/HEAD/skills/dev-desi ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/codeaholicguy/ai-devkit/blob/HEAD/skills/dev-desi ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 40 linesgithub.com/codeaholicguy/ai-devkit/blob/HEAD/skills/dev-desi ↗Pass
SKILL.md
View on GitHubDev Design
Run the design review phase for configured AI docs features. Before changing docs or code, propose the concrete plan for this phase and wait for user approval unless the user already approved the exact phase plan.
Phase Contract
- Run
npx ai-devkit@latest lintbefore phase work. - If working on a named feature, run
npx ai-devkit@latest lint --feature <name>. - Read existing requirements and design docs before changes.
- Ask until every material architecture, scope, validation, rollout, contradiction, trade-off, or open question is answered, explicitly deferred, or accepted as a named assumption.
- Ask one decision at a time, with why it matters, 2-3 viable options when useful, and a recommended answer.
- Do not approve or transition past design while material open questions remain.
- Use mermaid diagrams for architecture visuals where a diagram clarifies the design.
- If parent
dev-lifecycleestablished usable task tracing, emit design phase, progress, blocker/open-question, and next-step events pertask.
Review Design
Use for Phase 3.
- Run
npx ai-devkit@latest lint --feature <name>and review the design doc path it validates. If manual path resolution is unavoidable, first resolve.ai-devkit.jsonpaths.docs, falling back todocs/ai. - Search memory for relevant architecture patterns or past decisions.
- Cross-check against the latest matching requirements doc. Verify every goal, user story, and constraint has corresponding design coverage. Flag uncovered requirements.
- Review completeness: architecture, components, technology choices, data models, API contracts, design trade-offs, and non-functional requirements.
- Check usage-first design: APIs, CLI flows, UI flows, and docs should optimize for their caller/user, not implementation convenience.
- Screen design red flags: shallow modules, pass-through layers, temporal decomposition, leaked transport/storage/framework types, scattered validation, synchronized flags, and repeated conditionals where a domain model would fit.
- Resolve every gap, misalignment, open question, hidden assumption, or unresolved trade-off between requirements and design.
- Brainstorm alternatives for key architecture decisions and trade-offs before accepting the first approach.
- Prefer subtract-before-add sequencing: delete obsolete paths, consolidate redundant concepts, and narrow scope before adding new structure.
- Update the design doc with clarified decisions and chosen options.
- Store reusable architecture decisions in memory.
- If task tracing is available, record design coverage progress, next step, or blockers per
task. - Summarize requirements coverage, completeness assessment, updates made, and remaining gaps.
Next: dev-implementation. If requirements gaps are found, return to dev-requirements. If design is fundamentally wrong, revise design and re-review.
Files in this skill
2dev-design skill questions
How do I install the dev-design skill in Claude Code?
Run npx degit codeaholicguy/ai-devkit/skills/dev-design ~/.claude/skills/dev-design. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the dev-design skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
How do I start the design review process?
You should run the lint command using npx ai-devkit@latest lint, specifying the feature name if applicable.
What should the agent do if it finds gaps in the requirements?
If requirements gaps are identified, the agent should return to the dev-requirements phase.
How does the agent present architectural decisions?
The agent uses Mermaid diagrams to provide visual clarity for architecture designs.