octopus-architecture

Review system architecture, simplify boundaries, or compare interface designs from repository evidence

Quality

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

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

Quality

Content

78%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.

An impressively lean, guardrail-rich instruction skill with concrete output contracts, evidence requirements, and a well-defined two-draft comparison workflow. Its main weaknesses are the hard dependency on method files external to the bundle (which cannot be verified here) and workflows that are implicit rather than explicitly sequenced.

Suggestions

Vendor the referenced plugin blocks (skills/blocks/engineering-method-selection.md and skills/blocks/architecture-simplification.md) into the skill's own references/ directory, or inline the essential method steps, so the skill is self-contained.

Number the workflow steps (evidence gathering → boundary analysis → drafts → decision) and state where LSP verification occurs in that sequence.

Add a brief example of the Completion output (field names populated with a one-line sample) so the deliverable format is unambiguous.

Dimension	Reasoning	Score
Conciseness	Lean ~45 lines with zero padding: no concepts Claude already knows are explained, and every line carries instruction, guardrail, or output contract (e.g. "Pin the source revision and inspect implementation, callers, tests, recent churn, and failure behavior"). Matches anchor 5's 'every token earns its place'.	5 / 5
Actionability	Concrete, executable guidance for an instruction-only skill: a named evidence-gathering checklist, two defined draft objectives (A minimizes caller knowledge; B eases the next demonstrated extension), an explicit output field list, a decision enum with evidence requirements, and named LSP tools. Falls short of anchor 5 because the core method itself is delegated to skills/blocks/architecture-simplification.md and no output example is given.	4 / 5
Workflow Clarity	A clear Method → drafts → Completion sequence with real checkpoints ("Report incomplete independent coverage if that reviewer cannot read the source", "`simplify` requires exact source evidence and a concrete caller example", LSP results "verify consequential claims against source and tests"). Not anchor 5 because steps are unnumbered and the LSP stage's placement relative to the method is implicit.	4 / 5
Progressive Disclosure	The body is short and sectioned, but its core content depends on plugin-external files (skills/blocks/engineering-method-selection.md, skills/blocks/architecture-simplification.md) and THIRD_PARTY_NOTICES.md, none of which exist in this skill's bundle (no references/, scripts/, or assets/ directories). References are signaled but not resolvable within the bundle, matching anchor 3 rather than 4.	3 / 5
	Total	16 / 20 Passed

Description

66%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.

A concise, third-person description naming three concrete, domain-specific capabilities with an evidence grounding, but it lacks any 'Use when...' trigger clause, which caps its completeness and weakens its invocation behavior. Keyword coverage is good though missing common synonyms like "refactor" or "module boundaries".

Suggestions

Append an explicit trigger clause, e.g. "Use when the user asks to review or simplify system/module boundaries, compare interface or API designs, or decide whether to refactor an architecture."

Add natural synonyms and related phrasings users would say, such as "refactor boundaries", "module boundaries", "API design", or "architecture trade-offs".

Briefly name the expected deliverable (e.g. an evidence-backed proposed interface and migration plan) to sharpen the 'what' without adding fluff.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions ("Review system architecture, simplify boundaries, or compare interface designs") grounded by "from repository evidence". It falls short of anchor 5's comprehensive coverage because it names no deliverables or sub-capabilities, but clearly exceeds anchor 3's 1-2 actions.	4 / 5
Completeness	Has a clear 'what' but no 'Use when...' clause or equivalent explicit trigger guidance, which per judging guidelines caps completeness at 3. It is not a 2 because the 'what' is concrete and multi-action, and not a 4 because the 'when' is entirely absent rather than merely imprecise.	3 / 5
Trigger Term Quality	Includes natural phrases users would say ("system architecture", "simplify boundaries", "compare interface designs", "repository evidence"), matching anchor 4's 'good keyword coverage; a few natural terms missing'. Anchor 5 is not reached because common synonyms like "refactor", "module boundaries", or "API design" are absent.	4 / 5
Distinctiveness Conflict Risk	A fairly distinct niche (boundary simplification, interface comparison from repository evidence) with mostly distinct triggers, matching anchor 4. Not 5 because "review system architecture" overlaps with generic code-review and design-review skills.	4 / 5
	Total	15 / 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: nyldn/claude-octopus
Path: .claude/skills/skill-architecture/SKILL.md
Commit: 0093dab

Reviewed: 5 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.