trellis-update-spec

Captures executable contracts and coding conventions into .trellis/spec/ documentation files.

Updated Sep 5, 2026
One-click install
npx skills add https://github.com/jiozhaoyue/ST-BgLoader --skill trellis-update-spec-jiozhaoyue
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: trellis-update-spec
Source: https://github.com/jiozhaoyue/ST-BgLoader/tree/main/.cursor/skills/trellis-update-spec
Command: npx skills add https://github.com/jiozhaoyue/ST-BgLoader --skill trellis-update-spec-jiozhaoyue

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Valuable lessons learned during debugging, feature implementation, and design discussions are often lost between sessions, forcing developers and AI assistants to rediscover the same patterns and repeat the same mistakes. This Skill preserves that knowledge as executable code-specs in the .trellis/spec/ directory. ## Core Features & Use Cases - Executable Contract Capture: Records concrete signatures, request/response fields, environment keys, and validation/error matrices rather than vague principles. - Structured Update Workflow: Guides classification of learnings into design decisions, conventions, patterns, anti-patterns, common mistakes, and gotchas with ready-to-use Markdown templates. - Code-Spec vs Guide Distinction: Enforces correct placement of content between layer-specific spec files and thinking-checklist guides. - Use Case: After fixing a subtle cross-layer API bug, run this Skill to document the contract, error matrix, and a wrong-vs-correct example so future sessions implement it safely. ## Quick Start Update the code-spec to capture the validation contract and error handling pattern we just implemented for the backend API.

Frequently Asked Questions about trellis-update-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I document coding conventions learned during development?▼

Use this Skill after completing a task or fixing a bug to update the relevant file in .trellis/spec/. It classifies your learning as a design decision, convention, pattern, or gotcha and provides templates with concrete code examples.

What is the difference between a code-spec and a guide in Trellis?▼

Code-specs live in layer directories and define how to implement safely with signatures, contracts, and test points. Guides live in guides/ and are short thinking checklists pointing to specs. Content about how to write code belongs in specs; what to consider beforehand belongs in guides.

When is the full seven-section code-spec template required?▼

The mandatory seven sections apply when changes involve new or changed command/API signatures, cross-layer request/response contracts, database schema migrations, or infrastructure integrations such as storage, queues, caches, or environment wiring.

Should I update specs only after fixing bugs?▼

No. Spec updates apply to feature implementations, design decisions, discovered patterns, established conventions, and gotchas. Every implementation contains contracts that future developers and AI sessions need to execute safely.

What should a good code-spec update include?▼

Include specific actionable content with code examples, an explanation of why the rule exists, executable signatures and contracts, a validation and error matrix, good/base/bad cases, and required tests with assertion points.