CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

tech-debt

Maintain docs/TECH_DEBT.md, the living list of code-level cleanup that isn't a risk, a shortcut, or an open decision (that's the risk-register skill's job) and isn't a future feature (that's ROADMAP.md's job). Use when a lint/format/style violation slips past an existing gate, a small known cleanup is noticed while working on something else, or a filed item is fixed and needs removing. DO NOT use for anything with a real cost or risk if left unaddressed (use risk-register instead), for aislop baseline findings (already lifecycle-managed in .aislop/baseline.json), or for anything confidential. Triggers: 'add to tech debt', 'log this as cleanup', 'track this lint violation', 'mark tech-debt item #N fixed', 'what's on the tech debt list'.

Quality

86%

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

SKILL.md
Quality
Evals
Security

Quality

Content

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

A well-structured, highly actionable instruction skill: clear rules, concrete workflows with validation checkpoints, honest anti-patterns with WHY/BAD/GOOD, and correctly split one-level-deep references that all exist. Its main weakness is repetition — the deliberate-design rationale and launch-audit dates are restated across several sections, which costs tokens without adding information.

Suggestions

State the deletion-not-archive rationale once (Rule 1 or the intro) and have Mindset, Anti-Patterns, and the Scripts section reference Rule 1 instead of restating it.

Consolidate the 2026-07-31 audit / 2026-10-31 kill-criterion dates into a single place (e.g., one Maintenance/Kill-criterion section) instead of repeating them in Mindset and the relationship-to-risk-register section.

Include a single worked example row inline (or in the row template reference) at the point the Workflow describes field shapes, so a reader can draft a row without a second file hop.

DimensionReasoningScore

Conciseness

The body is dense with project-specific, non-obvious knowledge (no explanations of concepts Claude already knows), but the core deletion-not-archive rationale is repeated five times (intro paragraph, Rule 1, Mindset bullet 1, Anti-Pattern 1, Scripts note) and the 2026-07-31 audit date appears in three sections. Anchor 3 fits: mostly efficient but could be tightened; not 4 because the repetition goes beyond minor instances.

3 / 5

Actionability

Concrete guidance throughout: exact file paths, specific row-derivation steps ('the new row's # is that value + 1'), the exact command 'scripts/validate-tech-debt-schema.sh', and a concrete troubleshooting table. Mostly executable with minor gaps: no inline worked-example row (delegated to references/area-taxonomy-and-row-schema.md and the template), which keeps it below anchor 5.

4 / 5

Workflow Clarity

Both workflows are numbered with explicit validation ('Run scripts/validate-tech-debt-schema.sh before committing (the pre-commit hook runs it too...)') and due-diligence checkpoints before the destructive delete step ('Confirm the fix didn't reveal a real cost or risk'), plus error-recovery guidance for bounced commits. The destructive-operation cap does not apply: validation checkpoints are present.

5 / 5

Progressive Disclosure

References are one level deep, well signaled ('RECOMMENDED reading before filing or resolving a row: see [Area Taxonomy and Row Schema](references/area-taxonomy-and-row-schema.md)'), backed by a When-to-Use table, and every referenced path (references/area-taxonomy-and-row-schema.md, assets/templates/tech-debt-row-template.yaml, assets/schemas/tech-debt-row.schema.json, scripts/validate-tech-debt-schema.sh) exists. Anchor 4 rather than 5: the ~180-line body retains some content (repeated rationale, the relationship-to-risk-register discussion) that could be consolidated, a minor organization gap.

4 / 5

Total

16

/

20

Passed

Description

95%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 strong description: explicit what/when/when-not structure, a natural and comprehensive trigger list, and sharp boundaries against the sibling risk-register skill. The only soft spot is that the headline action ('Maintain docs/TECH_DEBT.md') is generic, with the concrete operations left implicit in the when-clauses.

DimensionReasoningScore

Specificity

Concrete actions are present via the when-clauses ('a lint/format/style violation slips past an existing gate', 'a filed item is fixed and needs removing') and boundary scoping, but the headline verb 'Maintain docs/TECH_DEBT.md' is itself generic. It sits above anchor 3 (only 1-2 concrete actions) because multiple specific operations are covered, but below anchor 5 (comprehensive list of concrete actions).

4 / 5

Completeness

Explicitly answers what ("the living list of code-level cleanup that isn't a risk, a shortcut, or an open decision") and when ("Use when a lint/format/style violation slips past an existing gate, a small known cleanup is noticed..., or a filed item is fixed and needs removing"), plus explicit DO-NOT-USE exclusions with concrete trigger phrases. Matches the anchor-5 example structure exactly.

5 / 5

Trigger Term Quality

A dedicated trigger list of natural user phrasings with synonyms: "'add to tech debt', 'log this as cleanup', 'track this lint violation', 'mark tech-debt item #N fixed', 'what's on the tech debt list". These are phrases a user would naturally say, covering add, track, resolve, and query. Not below 5: no common variation is obviously missing for this domain; file extensions don't apply to a doc-maintenance skill.

5 / 5

Distinctiveness Conflict Risk

Clear niche with explicit disambiguation: "that's the risk-register skill's job", "that's ROADMAP.md's job", "use risk-register instead", "already lifecycle-managed in .aislop/baseline.json". Triggers ('add to tech debt', 'track this lint violation') are distinct from the neighboring skills' vocabulary, so mis-trigger risk is minimal.

5 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 6 deeper-than-1-level

Warning

Total

15

/

16

Passed

Repository

pantheon-org/tekhne

Path

skills/project-mgmt/tech-debt/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.