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

65%

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

Quality

Content

65%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 admirably lean with well-signaled pointers, but it is an index whose targets are missing: the persona file, the full architecture rule, and the boundary-lint script are all outside the skill directory, and no in-bundle fallback exists. Inline the minimal actionable guidance (a lint command invocation and one example guardrail test) so the skill works standalone.

Suggestions

Ship the referenced files inside the skill bundle (references/architecture-rules.md, references/python-architect.persona.md, scripts/lint-architecture-boundaries.sh) and fix the relative links so navigation actually resolves.

Add one concrete executable example, e.g. the command to run the boundary check ('bash scripts/lint-architecture-boundaries.sh src/apm_cli/') and a minimal regression-test snippet demonstrating the dual guardrail.

Give the key rules an explicit ordering for a change (inspect existing patterns -> route through canonical owner -> add regression test -> add static check) so the workflow has sequence and validation checkpoints.

DimensionReasoningScore

Conciseness

The body is a lean set of pointer-style rules with zero padding — it assumes Claude's competence ('Prefer composition over deep inheritance') and never re-teaches known concepts, matching anchor 5's 'every token earns its place'.

5 / 5

Actionability

Rules name concrete authorities (BaseIntegrator, CommandLogger, AuthResolver, target_catalog, scripts/lint-architecture-boundaries.sh), but no executable commands or examples are given and the 'Full rule' is delegated to .apm/instructions/architecture.instructions.md, which is not part of the bundle — matching anchor 3's 'some concrete guidance but incomplete'. Not 4 because there is no code or runnable command to execute; not 2 because the guidance names specific classes and files rather than high-level hints.

3 / 5

Workflow Clarity

The body is a rules checklist with no sequence, no validation checkpoints beyond the dual-guardrail requirement itself, and its main instructions delegated to files absent from the bundle, so the single action is not self-contained enough for the simple-skill exception. Not 4 because there is no ordered process with checkpoints at all.

3 / 5

Progressive Disclosure

Sections are well organized and references are clearly signaled one level deep, but all three referenced paths (../../../.apm/agents/python-architect.agent.md, .apm/instructions/architecture.instructions.md, scripts/lint-architecture-boundaries.sh) point outside the skill and do not exist in the bundle, so navigation fails — per the guideline to score against the actual bundle structure this lands at anchor 3 rather than 4.

3 / 5

Total

14

/

20

Passed

Description

52%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 clause with concrete trigger conditions and a clear codebase-scoped niche, but it is entirely a 'when' statement. Adding a concise 'what' (e.g., 'Apply APM CLI architecture rules: follow existing base-class patterns, route decisions through canonical owners, guard centralization with tests and lint checks') would make it complete.

Suggestions

Add a one-phrase capability statement before the 'Activate when' clause so the description answers both 'what does this skill do' and 'when to use it'.

Include a couple of natural trigger synonyms users might say, such as 'adding a base class', 'restructuring packages', or 'extracting shared logic', to broaden natural-language matching.

Mention the concrete artifacts the skill governs (e.g., 'src/apm_cli/ modules, base classes, and boundary lint checks') so the description distinguishes itself from generic Python refactoring skills even outside the codebase qualifier.

DimensionReasoningScore

Specificity

The description lists several concrete trigger actions ('creating new modules', 'refactoring class hierarchies', 'introducing design patterns', 'changes spanning 3+ files') but never states what the skill actually does, so it falls between anchor 3 and 4 rather than matching anchor 4's 'several specific actions' with only minor gaps.

3 / 5

Completeness

Only the 'when' is present ('Activate when creating new modules, refactoring...') with no 'what' anywhere — matching anchor 2's 'only when is present without what'. It is not 3 because the 'what' is not even weakly implied, and not 1 because the 'when' clause is explicit and detailed.

2 / 5

Trigger Term Quality

Natural phrases a user would say ('new modules', 'refactoring', 'design patterns', '3+ files') are present with clear keywords, but common variations like 'class hierarchy', 'base class', or 'restructure' are missing, keeping it below anchor 5's comprehensive synonym coverage.

4 / 5

Distinctiveness Conflict Risk

Scoping to 'the APM CLI codebase' establishes a clear niche with minimal conflict risk, but the trigger terms alone ('new modules', 'design patterns') are generic and could overlap with general refactoring skills if the codebase qualifier is missed. Not 5 because the natural triggers are not uniquely distinctive on their own.

4 / 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

.agents/skills/python-architecture/SKILL.md

Revision

2920043

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill