ark-architecture
Design architecture for Ark features following existing patterns and principles. Use when planning new features, extending components, or evaluating technical approaches.
74
61%
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
57%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 an explicit 'Use when' clause, but suffers from vague, abstract language that doesn't convey concrete capabilities. The term 'Ark' provides some specificity to a particular project, but the actions described are too generic to clearly differentiate this skill or help Claude understand what it actually does.
Suggestions
Replace vague phrases like 'design architecture' and 'evaluating technical approaches' with specific concrete actions (e.g., 'Define module boundaries, plan data flow between services, create component hierarchies').
Add natural trigger terms users would actually say, such as specific Ark concepts, file types, or common phrases like 'how should I structure', 'design pattern for', or specific Ark component names.
Briefly clarify what 'Ark' is and what 'existing patterns and principles' refers to, so Claude can distinguish this from general software architecture skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description uses vague language like 'design architecture', 'planning new features', 'extending components', and 'evaluating technical approaches' without listing any concrete actions. It doesn't specify what kind of architecture, what patterns, or what 'Ark' is. | 1 / 3 |
Completeness | The description does answer 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 | Terms like 'architecture', 'features', 'components', and 'technical approaches' are somewhat relevant but generic. 'Ark' is a specific project name that could serve as a trigger, but the other terms are too broad and could match many different skills. | 2 / 3 |
Distinctiveness Conflict Risk | The mention of 'Ark' provides some distinctiveness, but terms like 'architecture', 'features', 'components', and 'technical approaches' are extremely broad and could easily overlap with many other development-related skills. | 2 / 3 |
Total | 8 / 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 skill that clearly communicates architectural principles and process for Ark features. Its main weakness is the lack of concrete, actionable examples—no sample architecture document, no template, and no executable guidance. The workflow would benefit from explicit validation checkpoints and feedback loops, especially given that architecture decisions can be hard to reverse.
Suggestions
Add a concrete example of an architecture document output (even abbreviated) showing the expected format for component diagrams, data models, and API designs
Add a validation/review checkpoint in the workflow, e.g., 'Before finalizing, verify the design reuses existing components by listing what's new vs extended'
Link to the ark-analysis skill explicitly and consider referencing any existing architecture documents or templates as examples
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. Every section adds value without explaining concepts Claude already knows. No padding or unnecessary context—just principles, conventions, and expected outputs. | 3 / 3 |
Actionability | The skill provides a clear process and principles but lacks concrete examples. There are no sample architecture documents, no example component diagrams, no template for the output format. The conventions section has two specific items (watch endpoints, service ports) which are good, but overall guidance is more directional 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 potentially irreversible decisions—there's no explicit review/validation step between designing and producing the output document. Step 5 mentions flagging one-way decisions but doesn't describe what to do if concerns are raised. | 2 / 3 |
Progressive Disclosure | The skill references the 'ark-analysis skill' in step 1 which is a good cross-reference, but doesn't link to it. There are no references to supporting documents for conventions, examples of architecture documents, or templates. For a skill that produces complex architecture documents, some reference to examples or templates would improve navigation. | 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
f4bfd2d
- 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.