trellis-update-spec

Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning something valuable from debugging, implementing, or discussion that should be preserved for future sessions.

Quality

63%

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 ./.cursor/skills/trellis-update-spec/SKILL.md

Quality

Content

63%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 highly actionable with concrete templates, decision rules, and a clear multi-step update workflow validated by a checklist. Its main weaknesses are verbosity from redundant/philosophical sections and a monolithic structure with no progressive disclosure despite its length.

Suggestions

Move the long Update Templates block into a separate references/templates.md file and link to it, keeping SKILL.md as an overview to improve progressive disclosure.

Trim the Core Philosophy section, the ASCII relationship diagram, and the Interactive Mode (which duplicates Step 2 classification) to reduce token load.

Add an explicit feedback loop to the workflow, e.g. 'If the Quality Checklist fails, revise the spec and re-run the checklist before finishing.'

Dimension	Reasoning	Score
Conciseness	The body is mostly concrete, project-specific guidance Claude would not already know, but at ~350 lines it carries padded sections (Core Philosophy quote, an ASCII relationship diagram, and an Interactive Mode that re-covers the Step 2 classification), fitting 'mostly efficient but could be tightened'.	3 / 5
Actionability	It provides copy-paste-ready markdown templates (7-section infra template, design decision, convention, pattern, forbidden pattern, gotcha) plus a concrete bash read command and explicit file paths, with only minor gaps from placeholder fields, matching 'mostly executable guidance with minor gaps'.	4 / 5
Workflow Clarity	The Update Process lays out a clear 5-step sequence (Identify, Classify, Read target, Update, Update index) with a final Quality Checklist as a validation checkpoint and a pre-edit read step, but lacks an explicit 'if checklist fails, revise and recheck' loop.	4 / 5
Progressive Disclosure	The skill is a monolithic ~350-line SKILL.md with no bundle files and no external references; it is well-sectioned with headers, but long template/tables content that could live in separate reference files is inlined, fitting 'some structure but content that should be separate is inline'.	3 / 5
	Total	14 / 20 Passed

Description

62%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 clearly states both what it does and when to use it, anchored to a project-specific .trellis/spec/ namespace that makes it reasonably distinct. It is somewhat limited in action breadth and trigger synonym coverage, keeping it just above midpoint.

Suggestions

Add one or two more concrete captured artifact types (e.g., 'signatures, payload fields, error matrices') to lift specificity toward comprehensive coverage.

Broaden trigger terms with natural synonyms users say, such as 'refactoring', 'design decisions', 'gotchas', or 'institutional memory'.

Tighten the 'when' clause to a sharper trigger, e.g. 'Use after fixing a bug, implementing a feature, or making a design decision worth preserving.'

Dimension	Reasoning	Score
Specificity	It names a concrete domain ('.trellis/spec/ documents', 'executable contracts and coding conventions') and the action 'Captures', but only 1-2 object types are covered, which matches the anchor for naming domain plus a couple concrete actions without being comprehensive.	3 / 5
Completeness	Both 'what' ('Captures executable contracts and coding conventions into .trellis/spec/ documents') and 'when' ('Use when learning something valuable from debugging, implementing, or discussion...') are explicitly present, though the 'when' could be marginally more specific, matching the both-present-with-minor-gaps anchor.	4 / 5
Trigger Term Quality	It includes natural trigger terms ('debugging', 'implementing', 'discussion') that users would say, but the framing 'learning something valuable' is abstract and common synonyms/variations are missing, fitting the 'some relevant keywords' anchor.	3 / 5
Distinctiveness Conflict Risk	The explicit '.trellis/spec/' namespace and 'executable contracts' framing carve a distinct niche with low conflict risk, with only minor overlap against general convention-documentation skills.	4 / 5
	Total	14 / 20 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: mindfold-ai/Trellis
Path: .cursor/skills/trellis-update-spec/SKILL.md
Commit: 64e6636

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