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

72%

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

Quality

Content

77%

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 and a clear, checkpointed workflow, scoring well on actionability and workflow clarity. Its main weaknesses are verbosity from duplicated/restated sections and a monolithic structure with no progressive disclosure of the template library into reference files.

Suggestions

De-duplicate the 7-section content: keep the full breakdown in one place (the template) and reference it from 'Mandatory Output' instead of restating it.

Collapse the overlapping When-to-update table, Interactive Mode, and Quality Checklist so each appears once and serves a distinct purpose.

Move the template library (design decision, convention, pattern, forbidden pattern, common mistake, gotcha) into a references/ file (e.g., TEMPLATES.md) and link to it from SKILL.md to add progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is project-specific rather than restating basics Claude knows, but it is padded: the 7-section list appears both in 'Mandatory Output (7 Sections)' and again in the template, and the When-to-update table, Interactive Mode, and Quality Checklist restate overlapping guidance.	2 / 3
Actionability	It provides a concrete file tree, a `cat .trellis/spec/...` command, and multiple copy-paste templates (design decision, convention, pattern, forbidden pattern, common mistake, gotcha) with clear placeholders, giving actionable guidance appropriate for an instruction skill.	3 / 3
Workflow Clarity	The Update Process is a clearly sequenced 5-step flow (identify -> classify -> read -> update -> update index) and is bookended by a 'before finishing' Quality Checklist checkpoint; the work is spec-doc editing rather than destructive/batch ops, so no retry loop is required.	3 / 3
Progressive Disclosure	No bundle files exist, so the skill is a single ~350-line monolithic SKILL.md; it is well-headed but content that could be split out (the template library) is inline, matching the score-2 anchor rather than a cleanly split score-3.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 cleanly states what the skill does and includes an explicit 'Use when' trigger, satisfying completeness. It is somewhat held back by a single-action verb and abstract trigger phrasing that limits specificity and trigger-term quality.

Suggestions

Expand the action list from the single verb 'Captures' to multiple concrete verbs (e.g., 'Creates, updates, and organizes executable contracts and coding conventions ...').

Replace the abstract 'learning something valuable' trigger with concrete natural-language cues a user would actually say (e.g., 'Use after fixing a bug, finishing a feature, or making a design decision worth remembering').

Tie the trigger more tightly to the .trellis/spec/ niche to reduce overlap with generic memory skills.

Dimension	Reasoning	Score
Specificity	It names the domain ('executable contracts and coding conventions') and a concrete action ('Captures ... into .trellis/spec/ documents'), but relies on a single verb rather than listing multiple specific actions, so it stops short of the score-3 anchor.	2 / 3
Completeness	It explicitly answers both what ('Captures executable contracts and coding conventions into .trellis/spec/ documents') and when via an explicit 'Use when ...' clause, matching the score-3 anchor and avoiding the missing-trigger cap at 2.	3 / 3
Trigger Term Quality	The 'Use when ... debugging, implementing, or discussion' clause surfaces some relevant terms, but the trigger phrasing 'learning something valuable ... that should be preserved' is abstract rather than crisp natural keywords users would say, missing common variations.	2 / 3
Distinctiveness Conflict Risk	The .trellis/spec/ target and 'executable contracts' framing carve a specific niche, but the broad 'preserve for future sessions' trigger could overlap with general memory/learning skills, so it is not yet a conflict-free score-3.	2 / 3
	Total	9 / 12 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: .agents/skills/trellis-update-spec/SKILL.md
Commit: 12e279a

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.