contribute

Guide for contributing to Trellis documentation and marketplace. Covers adding spec templates, marketplace skills, documentation pages, and submitting PRs across both the Trellis main repo and docs repo. Use when someone wants to add a new spec template, add a new skill to the marketplace, add or update documentation pages, or submit a PR to this project.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

71%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-organized, highly actionable contributing guide with concrete paths, registry snippets, commands, and per-flow numbered workflows backed by a PR checklist and pre-commit validation. Its main weakness is the absence of any progressive disclosure: four independent contribution workflows are all inlined in one long file, forcing the full ~415-line context to load when a contributor needs only one flow.

Suggestions

Split each contribution workflow (spec template, skill, showcase, documentation) into a one-level-deep reference file (e.g., references/spec-template.md, references/skill.md, references/showcase.md) and keep SKILL.md as a concise overview with the repo layout table, shared bilingual rules, and pointers to each flow.

In the Contributing a Skill section, show the exact docs.json JSON edit for the Skills nested group in both languages, as done for spec templates, rather than the vague "add your page to both languages".

Embed an explicit validation checkpoint in each workflow's numbered steps (e.g., "run `pnpm verify` after editing docs.json") instead of relying only on pre-commit hooks and the final PR checklist.

Dimension	Reasoning	Score
Conciseness	The body is dense with project-specific facts Claude would not know (repo trees, index.json registry format, docs.json navigation rules, install commands) with almost no generic explanation. Minor trimming is possible — the fully-commented docs/ tree partially duplicates the later Bilingual Requirements table, and the "Understanding docs.json" section could be tightened — matching anchor 4 rather than the fully lean anchor 5.	4 / 5
Actionability	Most guidance is copy-paste ready: exact file paths, complete index.json entries, frontmatter templates, `npx skills add` / `pnpm` / `git` commands, and Card component examples. Minor gaps remain — the skills section's step 4 ("add your page to both languages") omits the exact JSON shown for spec templates, matching anchor 4 rather than the fully executable anchor 5.	4 / 5
Workflow Clarity	Each contribution type (spec template, skill, showcase, docs) has a clearly numbered 1–5 sequence, and validation exists via pre-commit hooks (verify-docs.py), `pnpm dev`, and a final PR checklist. This is not a destructive/batch operation so the cap of 3 does not apply; validation is present but not embedded as explicit per-step checkpoints, which keeps it at anchor 4 rather than anchor 5.	4 / 5
Progressive Disclosure	All content is inlined in a single ~415-line SKILL.md with no reference files at all, even though the four contribution workflows (spec template, skill, showcase, documentation) are self-contained and could each live in a one-level-deep reference file — the body's own marketplace structure even documents `references/` support for skills. Internal header structure is good, but content that should be separate is inline, matching anchor 3; anchor 4 would require most content to be appropriately split across files.	3 / 5
	Total	15 / 20 Passed

Description

87%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 with a clear third-person statement of what the skill does, an explicit and concrete "Use when..." trigger clause, and tight scoping to the Trellis project that minimizes conflict risk. The only weakness is a small coverage gap: the showcase-project contribution flow documented in the body is absent from both the capability list and the trigger phrases.

Dimension	Reasoning	Score
Specificity	The description lists several concrete actions — "adding spec templates, marketplace skills, documentation pages, and submitting PRs" — but omits the showcase-project contribution flow that occupies an entire section of the body, so coverage has a minor gap (anchor 4) rather than being comprehensive (anchor 5).	4 / 5
Completeness	It clearly answers both questions: the "what" ("Guide for contributing to Trellis documentation and marketplace. Covers adding spec templates, marketplace skills, documentation pages, and submitting PRs...") and an explicit "Use when..." trigger clause enumerating concrete scenarios. This matches anchor 5; anchor 4 would require a weaker or less explicit "when" clause, which is not the case here.	5 / 5
Trigger Term Quality	Natural phrases users would say appear directly ("add a new spec template", "add a new skill to the marketplace", "submit a PR"), but coverage lacks synonyms and related natural terms such as "showcase", "marketplace listing", or file extensions. Good coverage with a few missing terms matches anchor 4; anchor 5's comprehensive synonym coverage is not met.	4 / 5
Distinctiveness Conflict Risk	The description is anchored to a specific niche — contributing to the named Trellis and docs repositories — with distinct triggers (spec templates, marketplace skills, PRs to this project), so the risk of firing for an unrelated skill is minimal. This matches anchor 5 rather than anchor 4, which would imply overlap with closely related skills.	5 / 5
	Total	18 / 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: .agents/skills/contribute/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.