ark-architecture
Design architecture for Ark features following existing patterns and principles. Use when planning new features, extending components, or evaluating technical approaches.
77
66%
Does it follow best practices?
Impact
95%
1.11xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./.claude/skills/architecture/SKILL.mdQuality
Discovery
67%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 good structural completeness with a clear 'Use when' clause, but suffers from vague action verbs and generic domain language. The project-specific term 'Ark' helps with distinctiveness but the capabilities described ('planning', 'extending', 'evaluating') are too abstract to strongly differentiate this skill or help Claude confidently select it over similar architecture/design skills.
Suggestions
Add more concrete actions specific to Ark architecture, e.g., 'Designs data models, defines API contracts, structures module hierarchies' instead of generic 'planning new features'.
Include more natural trigger terms users might say, such as 'design doc', 'system design', 'module layout', 'code structure', 'architectural decision'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain ('Ark features') and some actions ('planning new features, extending components, evaluating technical approaches'), but these actions are fairly high-level and not concrete enough to qualify as specific capabilities like 'extract text', 'fill forms', etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (design architecture for Ark features following existing patterns) and 'when' (planning new features, extending components, evaluating technical approaches) with an explicit 'Use when' clause. | 3 / 3 |
Trigger Term Quality | Includes some relevant terms like 'architecture', 'features', 'components', 'technical approaches', but 'Ark' is project-specific and the terms are somewhat generic. Missing natural variations a user might say like 'design doc', 'system design', 'module structure', 'refactor'. | 2 / 3 |
Distinctiveness Conflict Risk | The 'Ark' project name provides some distinctiveness, but 'architecture', 'planning features', and 'evaluating technical approaches' are broad enough to overlap with general coding, design, or planning skills. Could conflict with other architecture or design-related skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
64%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, concise architecture guidance skill that effectively communicates principles and conventions without unnecessary verbosity. However, it lacks concrete examples (e.g., a sample architecture document or template) and validation checkpoints in the workflow, which limits its actionability for producing consistent, high-quality outputs.
Suggestions
Add a concrete example of a completed architecture document (even a brief one) showing the expected output format with component diagram notation, data model extension, and API design sections.
Include a validation step in the process, such as 'Verify the design reuses existing patterns by cross-referencing with ark-analysis output' or a checklist before finalizing.
Provide a link or path to the referenced 'ark-analysis skill' so Claude can navigate to it directly.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. Every section serves a purpose, there's no explanation of concepts Claude already knows, and the principles/conventions are stated as terse, actionable bullet points. | 3 / 3 |
Actionability | The skill provides a clear process and principles but lacks concrete examples—no sample architecture document, no code snippets, no template showing what a component diagram or API design section should look like. The guidance is directional rather than executable. | 2 / 3 |
Workflow Clarity | The 5-step process is clearly sequenced, but there are no validation checkpoints or feedback loops. For architecture design (which involves one-way decisions), there's no explicit step to verify the design against existing patterns or get confirmation before proceeding. | 2 / 3 |
Progressive Disclosure | The skill references the 'ark-analysis skill' but provides no link or path to it. There are no bundle files or referenced documents for deeper content like example architecture documents or convention details. The content is well-organized but could benefit from clear references to supporting materials. | 2 / 3 |
Total | 9 / 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
- mckinsey/agents-at-scale-ark
- Commit
6b7c761
- 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.