tech-design
Use when prd.md is approved and the Scope Proposal has no remaining ⚡ items. Covers system design, API contracts, DB schema, and infra. Requires GitHub MCP. Run after /analyze and the joint alignment meeting.
64
76%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/tech-design/SKILL.mdQuality
Discovery
75%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description has strong completeness with explicit 'Use when' triggers and clear preconditions, making it highly distinctive within a workflow. However, it leans heavily on internal process terminology and lists topic areas rather than concrete actions, which weakens specificity and trigger term quality for users who might not use the exact internal vocabulary.
Suggestions
Replace topic listings ('Covers system design, API contracts, DB schema, and infra') with concrete actions (e.g., 'Designs system architecture, defines API contracts, creates DB schemas, plans infrastructure').
Add natural-language trigger terms users might say, such as 'technical design', 'architecture document', 'tech spec', 'design doc' alongside the process-specific triggers.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names several domain areas (system design, API contracts, DB schema, infra) but doesn't describe concrete actions—it lists topics covered rather than specific operations performed. | 2 / 3 |
Completeness | Explicitly answers both 'what' (covers system design, API contracts, DB schema, and infra) and 'when' (use when prd.md is approved and Scope Proposal has no remaining ⚡ items, run after /analyze and alignment meeting). The 'Use when' clause is present and detailed with explicit triggers. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'system design', 'API contracts', 'DB schema', and 'infra', but relies heavily on internal process jargon ('prd.md', 'Scope Proposal', '⚡ items', '/analyze', 'joint alignment meeting') that users wouldn't naturally say. Missing common variations a user might use. | 2 / 3 |
Distinctiveness Conflict Risk | The very specific preconditions (approved prd.md, no remaining ⚡ items in Scope Proposal, after /analyze and alignment meeting) create a clear niche that is unlikely to conflict with other skills. The combination of workflow stage and technical domain is highly distinctive. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent workflow clarity and concrete examples. The precondition checks, approval flow, and re-entry instructions demonstrate thoughtful process design. The main weakness is moderate verbosity — some sections could be tightened, and the detailed output template could potentially be extracted to a reference file for better progressive disclosure.
Suggestions
Consider extracting the detailed tech design output template (System Overview through Open Technical Questions) into a separate reference file like `tech-design-template.md` to keep the SKILL.md focused on the workflow.
Tighten the Notes section — the first bullet about when to skip could be shortened, and the re-entry note could be more concise since the concept is straightforward.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and avoids explaining concepts Claude already knows, but there's some verbosity in the notes section and repeated explanations (e.g., the EA/GA tagging concept is explained multiple times). The precondition error messages are helpful but slightly wordy. | 2 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific file paths, exact output format with SQL and API contract examples, precise precondition checks with exact error messages, and a clear approval workflow with specific response text. The examples for API contracts and database schema are copy-paste ready templates. | 3 / 3 |
Workflow Clarity | The 5-step workflow is clearly sequenced with explicit precondition gates (stop if PRD not approved, stop if scope unresolved), a defined scan strategy, a structured output template, and a review/approval checkpoint with re-entry instructions for scope changes. The feedback loop for approval and the re-entry note for scope changes are well-handled. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear sections and headers, but it's a fairly long monolithic document with no references to supporting files. The detailed API contract format, DB schema examples, and section templates could be split into a reference file. However, given no bundle files exist, this is somewhat expected — the inline detail is necessary but makes the skill lengthy. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- PagerDuty/ai-forward-planning
- Commit
585e8a6
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.