python-architecture

Activate when creating new modules, refactoring class hierarchies, introducing design patterns, or making changes spanning 3+ files in the APM CLI codebase.

Quality

70%

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 ./.agents/skills/python-architecture/SKILL.md

Quality

Content

72%Weight 40%Scale 1-3

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

The body is an efficiently written, well-organized overview that defers detail to clearly signaled one-level references. Its gaps are procedural: it gives principle-level guidance without executable examples, and lacks an explicit sequenced workflow even though it describes a validation guardrail.

Suggestions

Add at least one concrete executable example, such as the command to run `scripts/lint-architecture-boundaries.sh` and a minimal regression-test snippet illustrating the 'dual guardrail'.

Turn the centralization rule into a short sequenced checklist (identify the canonical owner -> route through it -> extend not fork -> add regression test -> run the static check) so the workflow and validation checkpoint are explicit.

Dimension	Reasoning	Score
Conciseness	The body is lean with no concept explanation, assuming Claude knows composition, inheritance, and design patterns; each line is a concrete rule or trigger, so every token earns its place.	3 / 3
Actionability	It names concrete authorities (BaseIntegrator, CommandLogger, AuthResolver, etc.) and a specific lint script, but provides no executable commands or examples — the guidance is principle-level ('route through', 'extend, never fork') rather than copy-paste ready, matching 'some concrete guidance but incomplete'.	2 / 3
Workflow Clarity	Sections ('When to activate', 'Key rules') are organized and a validation concept exists (the dual guardrail), but there is no explicit multi-step sequence with ordered checkpoints; the rules are principles rather than a sequenced workflow.	2 / 3
Progressive Disclosure	The body is a lean overview pointing to well-signaled one-level-deep references ('Full rule: .apm/instructions/architecture.instructions.md', the persona link, and the lint script) with no nested reference chains; not a 2 because the split is clean and navigation is easy.	3 / 3
	Total	10 / 12 Passed

Description

67%Weight 40%Scale 1-3

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 is concise, third-person, and well-scoped to a specific codebase with an explicit activation trigger. Its main weakness is that it states when to activate but never explicitly states what the skill does, leaving the capability implied.

Suggestions

Add a brief capability clause stating what the skill does (e.g., 'Applies APM CLI architecture conventions: centralizes logic behind canonical owners and guards each centralization') before the 'Activate when' trigger.

Broaden trigger terms with natural user phrasings and common variations (e.g., 'refactor', 'restructure', 'add a base class', 'shared logic across files') alongside the current technical vocabulary.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'creating new modules, refactoring class hierarchies, introducing design patterns, or making changes spanning 3+ files' — matching the multi-action anchor; it is not the level below because the actions are named explicitly rather than a vague domain reference.	3 / 3
Completeness	An explicit 'Activate when' trigger clause satisfies the 'when', but the 'what does this do' capability is only implied through the trigger list rather than stated, so it does not clearly answer both; not a 3 because 'what' is not explicitly articulated.	2 / 3
Trigger Term Quality	Terms like 'refactoring class hierarchies' and 'design patterns' are relevant developer vocabulary but lean technical and lack common variations, matching 'some relevant keywords but missing common variations'; not a 3 because there is no broad coverage of natural phrasings a user would actually say.	2 / 3
Distinctiveness Conflict Risk	Scoping to 'the APM CLI codebase' with triggers like 'class hierarchies', 'design patterns', and '3+ files' carves a clear niche unlikely to fire for unrelated skills; not a 2 because the codebase binding and architecture framing make overlap unlikely.	3 / 3
	Total	10 / 12 Passed

Validation

87%

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 — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 suspicious	Warning
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: microsoft/apm
Path: .agents/skills/python-architecture/SKILL.md
Commit: 634f7b6

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