ark-architecture

Design architecture for Ark features following existing patterns and principles. Use when planning new features, extending components, or evaluating technical approaches.

1.11x

Quality

63%

Does it follow best practices?

Impact

95%

1.11x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.claude/skills/architecture/SKILL.md

Quality

Content

65%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a compact, well-structured instruction skill that assumes Claude's intelligence and gives a clear sequenced process plus concrete conventions and an output checklist. Its gaps are abstract process directives without execution specifics and a missing validation/review checkpoint in the workflow.

Suggestions

Tighten actionability by adding concrete execution cues to each process step, e.g. what artifacts to inspect with ark-analysis, how to locate reusable models, and a concrete heuristic for spotting a one-way decision.

Add an explicit validation/review checkpoint to the workflow, e.g. '6. Review the draft against the Output checklist and confirm no one-way decision is left unflagged before sharing'.

Collapse the overlap between Process and Principles into a single section to remove the duplicated reuse/reversibility/incremental messaging and reach full conciseness.

Dimension	Reasoning	Score
Conciseness	The body is lean with no padding and assumes Claude's competence, but the Process and Principles sections restate overlapping ideas (reuse, reversibility, incremental delivery), which is a minor inefficiency keeping it just below anchor 5.	4 / 5
Actionability	The Conventions ('?watch=true', named ports) and Output list are concrete, but the core Process steps are high-level directives ('Find existing idioms', 'Extend existing components') missing the specifics needed to execute, matching 'some concrete guidance but incomplete; missing key details'.	3 / 5
Workflow Clarity	There is a clear 5-step numbered sequence (Analyze -> Identify -> Design -> Enable -> Flag), but no explicit validation or feedback checkpoint verifying the design, fitting 'steps listed but validation gaps; checkpoints missing or implicit'.	3 / 5
Progressive Disclosure	At under 50 lines with no need for external references and well-organized sections (Process, Principles, Conventions, Output), this meets the simple-skills exception where progressive disclosure scores 5 on well-organized sections alone.	5 / 5
	Total	15 / 20 Passed

Description

62%Weight 40%Scale 1-5

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 clearly states both capability and an explicit 'Use when' trigger clause tied to a specific codebase niche. Its main weakness is abstract rather than concrete action and trigger language, which keeps specificity and trigger-term quality at the midpoint.

Suggestions

Replace abstract verbs with more concrete actions, e.g. 'Design and document component diagrams, data models, and API contracts for Ark features' to lift specificity.

Add natural user-facing trigger phrases and synonyms, e.g. 'Use when the user asks how to architect a new Ark feature, extend an existing service, or compare design approaches'.

Dimension	Reasoning	Score
Specificity	The description names the domain ('Ark features') and several actions ('Design architecture', 'planning', 'extending', 'evaluating'), but these are abstract directives rather than concrete operations like the PDF anchors, fitting 'names domain and 1-2 concrete actions but not comprehensive' better than anchor 4.	3 / 5
Completeness	It explicitly answers both 'what' ('Design architecture for Ark features...') and 'when' ('Use when planning new features...'), but the trigger phrases are somewhat abstract, so it sits at anchor 4 rather than the fully concrete trigger coverage of anchor 5.	4 / 5
Trigger Term Quality	Trigger phrases 'planning new features, extending components, or evaluating technical approaches' are relevant but fairly generic/technical with no synonyms or common variations, matching 'some relevant keywords but missing common variations or synonyms' rather than the fuller coverage of anchor 4.	3 / 5
Distinctiveness Conflict Risk	The 'Ark' qualifier gives a clear niche, but the generic triggers ('planning new features', 'extending components', 'evaluating technical approaches') create minor overlap risk with related architecture/design skills, matching 'mostly distinct; minor overlap risk'.	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mckinsey/agents-at-scale-ark
Path: .claude/skills/architecture/SKILL.md
Commit: 26d4d0b

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.