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

73%

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 skill delivers concrete, actionable templates and a clearly sequenced five-step process, but it is a single monolithic file with all template content inlined and some redundant filler. Splitting the templates into reference files and trimming duplicated table rows would lift most dimensions.

Suggestions

Move the six update templates and the Interactive Mode prompts into a references/ file (e.g., references/templates.md) and keep only the decision tables and process steps in SKILL.md.

Remove the duplicate "Convention" row in the update-type table and the verbatim repeat of the 7-section list in the template section; cross-reference one from the other instead.

Include one fully filled-in example of the 7-section scenario template so users see what a completed code-spec update looks like, and convert the Quality Checklist into a verify/fix/re-run loop.

Dimension	Reasoning	Score
Conciseness	The body is mostly purposeful but noticeably padded: the update-type table contains near-duplicate "Project Convention" and "Convention" rows, the mandatory 7-section list is repeated verbatim in the template section, and the flow diagram and philosophy sections add little actionable value.	3 / 5
Actionability	Copy-paste-ready markdown templates for each update type plus a concrete command ("cat .trellis/spec/<category>/<file>.md") give mostly executable guidance; the gap is that templates are never shown filled in with a real worked example.	4 / 5
Workflow Clarity	Steps 1-5 are clearly sequenced and include a pre-edit read step and a closing Quality Checklist as validation checkpoints, but the checklist is a list of yes/no questions rather than an explicit validate/fix/retry feedback loop.	4 / 5
Progressive Disclosure	Section headers organize the ~355-line body well, but everything is inlined monolithically — the ~150 lines of update templates and the interactive-mode prompts clearly belong in separate reference files, and no bundle files exist at all.	3 / 5
	Total	14 / 20 Passed

Description

70%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 solid description in correct third-person voice that pairs a concrete "what" with an explicit "Use when" clause naming debugging, implementing, and discussion as triggers. Its main weaknesses are limited action coverage (only two named actions) and mildly elastic trigger phrasing ("something valuable").

Suggestions

Enumerate the concrete capture actions more fully (e.g., "documents signatures, error matrices, validation rules, and conventions") to raise specificity.

Add natural trigger synonyms such as "documenting learnings", "updating the spec", or "preserving conventions for future sessions".

Dimension	Reasoning	Score
Specificity	"Captures executable contracts and coding conventions into .trellis/spec/ documents" names the domain and 1-2 concrete actions with a specific destination, but does not enumerate several specific actions as anchor 4 requires.	3 / 5
Completeness	It answers both "what" ("Captures executable contracts and coding conventions into .trellis/spec/ documents") and an explicit "Use when..." clause with three trigger contexts, but "something valuable... that should be preserved" is slightly elastic rather than fully concrete, keeping it below anchor 5.	4 / 5
Trigger Term Quality	"Use when learning something valuable from debugging, implementing, or discussion" covers good natural trigger phrases, but misses common synonyms like "documenting learnings" or "updating the spec".	4 / 5
Distinctiveness Conflict Risk	The .trellis/spec/ niche and code-spec framing make it mostly distinct from other skills, with only minor overlap risk with generic note-taking/memory skills triggered by phrases like "learning something valuable".	4 / 5
	Total	15 / 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: f089cb3

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