CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

72%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.apm/skills/python-architecture/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

DimensionReasoningScore

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

Description

57%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 tightly scoped, correctly third-person description with strong, concrete activation triggers, but it is one-sided: it is entirely a 'when' clause with no statement of what the skill does or what following it yields. The 3+ files trigger is also broad enough to risk overlapping activation on non-architectural multi-file changes.

Suggestions

Lead with a short capability statement before the trigger clause, e.g. 'Applies and enforces the APM CLI's architecture rules (canonical owners, base-class shared logic, dual guardrails). Activate when...' — this would fix the missing 'what' that caps completeness and specificity.

Narrow or qualify the 'changes spanning 3+ files' trigger (e.g. '3+ files sharing logic patterns' or 'changes that would duplicate logic across siblings') so it does not fire on bulk renames or incidental multi-file edits.

Add a few natural synonyms users would actually say — 'base class', 'restructure', 'refactor into a pattern', 'Strategy/Observer' — to lift trigger-term coverage from good to comprehensive.

DimensionReasoningScore

Specificity

Phrases like "creating new modules, refactoring class hierarchies, introducing design patterns, or making changes spanning 3+ files" list several concrete, domain-specific actions, but they are all trigger conditions — the description never states what the skill actually does (provide architectural rules/guidance), so coverage of capabilities is one-sided. This sits between anchor 3 (1-2 concrete actions, not comprehensive on the capability side) and anchor 4 (several specific actions), with the missing 'what' keeping it at 3 rather than 4.

3 / 5

Completeness

The 'when' is fully explicit ("Activate when creating new modules, refactoring class hierarchies, introducing design patterns, or making changes spanning 3+ files in the APM CLI codebase"), but the 'what' is entirely absent — the description is a pure trigger clause with no statement of capability, mirroring anchor 3's incompleteness in reverse. It is above anchor 2 ('only when present') because that anchor's example is vague, whereas here the 'when' is detailed and concrete; it cannot reach 4 because anchor 4 requires both what AND when.

3 / 5

Trigger Term Quality

"creating new modules", "refactoring class hierarchies", "introducing design patterns", and "changes spanning 3+ files" are phrases a user would plausibly say verbatim when needing this skill, matching anchor 4's 'good keyword coverage; a few natural terms missing'. It falls short of 5 because natural synonyms users might say — e.g. 'base class', 'restructure', 'abstraction', or pattern names like 'Strategy/Observer' — appear only in the body, not in the description.

4 / 5

Distinctiveness Conflict Risk

The scope to "the APM CLI codebase" and architectural vocabulary ("class hierarchies", "design patterns") give it a clear niche, but the very broad trigger "making changes spanning 3+ files" would fire on many multi-file changes that are not architectural — e.g. renames, bulk edits, or test additions — creating real overlap risk with general refactoring or code-review skills. This matches anchor 3 ('somewhat specific but could still overlap with similar skills'); not 4 because the 3+ files trigger is a common situation rather than a distinct architectural signal.

3 / 5

Total

13

/

20

Passed

Validation

87%

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

CriteriaDescriptionResult

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

Reviewed

Table of Contents

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.