Content
76%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
An exemplarily lean, concrete rules-overview for an instruction-only skill: it names real classes, authorities, and an enforcement script instead of vague principles. Its main weaknesses are the absence of any ordered workflow for the multi-file refactors it targets and references to files that are not shipped in the skill bundle.
Suggestions
Add a short ordered sequence for architectural changes (survey existing patterns → route the decision through its canonical owner → implement → lock with regression test + `lint-architecture-boundaries.sh`), which would make the implicit workflow explicit and integrate the existing guardrail as a checkpoint.
Ship or verify the referenced files — `scripts/lint-architecture-boundaries.sh`, `.apm/instructions/architecture.instructions.md`, and the linked agent persona — inside the skill bundle, or inline the critical bits, so the guardrail step is actually executable from what the skill provides.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~25-line body is lean and assumes Claude's competence throughout — no explanation of what design patterns are, why composition beats inheritance, or what a regression test is; every line is either a rule or a pointer ("Prefer composition over deep inheritance", "extend it, never fork it"). It matches anchor 5 ('lean and efficient; every token earns its place') and clearly not anchor 4, which reserves room for over-explanation that is simply absent here. | 5 / 5 |
Actionability | For an instruction-only skill the guidance is concrete: it names the patterns to follow ("BaseIntegrator, CommandLogger, AuthResolver"), enumerates the exact canonical owners to route through, and specifies a verifiable enforcement step — "a regression test plus a static check in `scripts/lint-architecture-boundaries.sh`". This is mostly-executable per anchor 4; it stops short of 5 because the referenced script and the full rule file are not present in the skill bundle, so the guardrail command cannot actually be run or copied from what is shipped. | 4 / 5 |
Workflow Clarity | No sequence is given for an architectural change (when to inspect existing patterns, when to introduce a base class, when to add the guardrail); the guidance is a rules list, and the one checkpoint that does exist — the dual guardrail of regression test plus lint check — is stated as a rule, not woven into an ordered workflow. That matches anchor 3 ('sequence present but checkpoints missing or implicit' — here the checkpoints are isolated and the sequence implicit); it cannot score 4 because the simple-skill exception does not apply: this skill explicitly targets complex 3+ file refactors, a multi-step process, and the ordering of analysis → design → guardrail is left implicit. | 3 / 5 |
Progressive Disclosure | The body is a clean overview with clear sections ('When to activate', 'Key rules'), and the longest rule — canonical ownership — correctly inlines only a summary while pointing to the full rule at `.apm/instructions/architecture.instructions.md`, exactly the one-level-deep pattern anchor 4 describes. It does not reach 5 because the bundle contains no references/, scripts/, or assets/ directories, so the three referenced paths (`scripts/lint-architecture-boundaries.sh`, `.apm/instructions/architecture.instructions.md`, `../../agents/python-architect.agent.md`) are unverifiable or outside the skill, leaving minor organization gaps. | 4 / 5 |
Total | 16 / 20 Passed |