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

67%

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

Quality

Content

68%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 concise, well-structured overview that points to detailed materials via clearly signaled one-level-deep references and names concrete architectural authorities, but it provides no sequenced workflow or executable code examples.

Suggestions

Add a short numbered workflow with an explicit validation checkpoint (e.g., 1. identify shared logic, 2. route through canonical owner, 3. run scripts/lint-architecture-boundaries.sh, 4. add regression test) to lift workflow clarity above the destructive-change cap.

Show the actual lint invocation command (e.g., 'bash scripts/lint-architecture-boundaries.sh') rather than only naming the script path, to make the guardrail copy-paste ready.

Either add a one-line gloss for the persona link or fold the long canonical-owner list into the referenced architecture.instructions.md to tighten conciseness and navigation.

Dimension	Reasoning	Score
Conciseness	The body is lean — terse bullet lists with no concept explanations Claude already knows — and assumes competence; not a 5 because the long canonical-owner enumeration in the last 'Key rules' bullet is dense and could be trimmed or moved to the referenced file.	4 / 5
Actionability	Directives name concrete entities (BaseIntegrator, CommandLogger, AuthResolver) and a specific script path ('scripts/lint-architecture-boundaries.sh'), giving mostly actionable guidance; not a 5 because no executable command or code example is shown, only a referenced script path.	4 / 5
Workflow Clarity	This is a principles/rules skill with no sequenced workflow, though it does name a validation guardrail ('a regression test plus a static check'); the missing explicit step sequence keeps it at the cap appropriate for multi-file/destructive changes without a gated workflow.	3 / 5
Progressive Disclosure	Clear section headers organize the overview and external materials are one-level-deep and signaled ('Full rule: .apm/instructions/architecture.instructions.md'); not a 5 because the persona link sits unexplained at the top and no bundle files exist to verify the referenced paths.	4 / 5
	Total	15 / 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.

The description has a strong, explicit activation trigger with concrete, natural developer terms and good codebase scoping, but it never states what the skill does — the capability is only implied, leaving completeness as the weakest dimension.

Suggestions

Lead with an explicit capability statement (e.g., 'Provides Python architecture guidance for...') before the 'Activate when' clause so the 'what' is stated, not just implied.

Add a few natural synonyms or concrete tokens users might say (e.g., 'base classes', 'shared logic', 'module structure') to broaden trigger coverage.

Tighten distinctiveness by tying triggers more tightly to APM CLI-specific architectural authorities rather than general refactoring terms.

Dimension	Reasoning	Score
Specificity	Lists several concrete trigger actions — 'creating new modules, refactoring class hierarchies, introducing design patterns' and 'changes spanning 3+ files' — matching the 'several specific actions, minor gaps' anchor; not a 5 because these are situations rather than an exhaustive set of the skill's capabilities.	4 / 5
Completeness	The 'when' is explicit and strong ('Activate when...'), but no explicit 'what' states what the skill actually does — the capability is only implied by the name and trigger list, sitting between the only-when-no-what anchor (2) and the both-present anchor (4).	3 / 5
Trigger Term Quality	Uses natural developer terms ('refactoring class hierarchies', 'design patterns', 'new modules', '3+ files') that a user would plausibly say; not a 5 because it lacks synonyms or file/extension variants.	4 / 5
Distinctiveness Conflict Risk	Scoping to 'the APM CLI codebase' plus specific architectural triggers makes it mostly distinct from generic coding skills; not a 5 because 'creating new modules' and 'refactoring' still overlap with general development skills.	4 / 5
	Total	15 / 20 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: .apm/skills/python-architecture/SKILL.md
Commit: 71a877c

Reviewed: ~3 hours 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.