SkillAgentSearch skills...

trellis-update-spec

Captures executable contracts and coding conventions into .trellis/spec/ documents

Install / Use

npx skills add fy-agent/fyagent --skill trellis-update-spec

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

89/100

Supported Platforms

Universal

Tags

Our assessment of trellis-update-spec

trellis-update-spec scores 89/100 on our quality scale, 523rd of 1,155 Content & Media skills we index (top 46%).

Its SKILL.md is 9.8 KB long, well organised into 40 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.

With 1,181 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
13/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so trellis-update-spec is actively maintained.
  • Our last check on 2026-10-31 found the source still online.
  • No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
  • Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

trellis-update-spec compared with similar skills

All 4 of these similar skills score higher than trellis-update-spec; compare them before choosing.

SkillScoreStarsUpdatedFormat
trellis-update-spec (this skill)by fy-agent891.2k55d agoSKILL.md
siyuanby siyuan-note10047.3ktodayMCP Server
x402by browser-use100121.0k3d agoSKILL.md
algorithmic-artby anthropics100177.9k55d agoSKILL.md
pptxby anthropics100177.9k55d agoSKILL.md

Frequently asked questions

How do I install trellis-update-spec?
Run npx skills add fy-agent/fyagent --skill trellis-update-spec. The install tabs above show the steps for each supported agent.
Which AI agents does trellis-update-spec work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is trellis-update-spec safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is trellis-update-spec still maintained?
The repository was last updated about 2 months ago, so trellis-update-spec is actively maintained.

name: trellis-update-spec description: "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."

Update Code-Spec - Capture Executable Contracts

When you learn something valuable (from debugging, implementing, or discussion), use this to update the relevant code-spec documents.

Timing: After completing a task, fixing a bug, or discovering a new pattern


Code-Spec First Rule (CRITICAL)

In this project, "spec" for implementation work means code-spec:

  • Executable contracts (not principle-only text)
  • Concrete signatures, payload fields, env keys, and boundary behavior
  • Testable validation/error behavior

If the change touches infra or cross-layer contracts, code-spec depth is mandatory.

Mandatory Triggers

Apply code-spec depth when the change includes any of:

  • New/changed command or API signature
  • Cross-layer request/response contract change
  • Database schema/migration change
  • Infra integration (storage, queue, cache, secrets, env wiring)

Mandatory Output (7 Sections)

For triggered tasks, include all sections below:

  1. Scope / Trigger
  2. Signatures (command/API/DB)
  3. Contracts (request/response/env)
  4. Validation & Error Matrix
  5. Good/Base/Bad Cases
  6. Tests Required (with assertion points)
  7. Wrong vs Correct (at least one pair)

When to Update Code-Specs

| Trigger | Example | Target Spec | |---------|---------|-------------| | Implemented a feature | Added a new integration or module | Relevant spec file | | Made a design decision | Chose extensibility pattern over simplicity | Relevant spec + "Design Decisions" section | | Fixed a bug | Found a subtle issue with error handling | Relevant spec (e.g., error-handling docs) | | Discovered a pattern | Found a better way to structure code | Relevant spec file | | Hit a gotcha | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section | | Established a convention | Team agreed on naming pattern | Quality guidelines | | New thinking trigger | "Don't forget to check X before doing Y" | guides/*.md (as a checklist item) |

Key Insight: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.


Spec Structure Overview

.trellis/spec/
├── <layer>/           # Per-layer coding standards (e.g., backend/, frontend/, api/)
│   ├── index.md       # Overview and links
│   └── *.md           # Topic-specific guidelines
└── guides/            # Thinking checklists (NOT coding specs!)
    ├── index.md       # Guide index
    └── *.md           # Topic-specific guides

CRITICAL: Code-Spec vs Guide - Know the Difference

| Type | Location | Purpose | Content Style | |------|----------|---------|---------------| | Code-Spec | <layer>/*.md | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points | | Guide | guides/*.md | Help AI "what to think about" | Checklists, questions, pointers to specs |

Decision Rule: Ask yourself:

  • "This is how to write the code" → Put in a spec layer directory
  • "This is what to consider before writing" → Put in guides/

Example:

| Learning | Wrong Location | Correct Location | |----------|----------------|------------------| | "Use API X not API Y for this task" | ❌ guides/ (too specific for a thinking guide) | ✅ Relevant spec file (concrete convention) | | "Remember to check X when doing Y" | ❌ Spec file (too abstract for a spec) | ✅ guides/ (thinking checklist) |

Guides should be short checklists that point to specs, not duplicate the detailed rules.


Update Process

Step 1: Identify What You Learned

Answer these questions:

  1. What did you learn? (Be specific)
  2. Why is it important? (What problem does it prevent?)
  3. Where does it belong? (Which spec file?)

Step 2: Classify the Update Type

| Type | Description | Action | |------|-------------|--------| | Design Decision | Why we chose approach X over Y | Add to "Design Decisions" section | | Project Convention | How we do X in this project | Add to relevant section with examples | | New Pattern | A reusable approach discovered | Add to "Patterns" section | | Forbidden Pattern | Something that causes problems | Add to "Anti-patterns" or "Don't" section | | Common Mistake | Easy-to-make error | Add to "Common Mistakes" section | | Convention | Agreed-upon standard | Add to relevant section | | Gotcha | Non-obvious behavior | Add warning callout |

Step 3: Read the Target Code-Spec

Before editing, read the current code-spec to:

  • Understand existing structure
  • Avoid duplicating content
  • Find the right section for your update
cat .trellis/spec/<category>/<file>.md

Step 4: Make the Update

Follow these principles:

  1. Be Specific: Include concrete examples, not just abstract rules
  2. Explain Why: State the problem this prevents
  3. Show Contracts: Add signatures, payload fields, and error behavior
  4. Show Code: Add code snippets for key patterns
  5. Keep it Short: One concept per section

Step 5: Update the Index (if needed)

If you added a new section or the code-spec status changed, update the category's index.md.


Update Templates

Mandatory Template for Infra/Cross-Layer Work

## Scenario: <name>

### 1. Scope / Trigger
- Trigger: <why this requires code-spec depth>

### 2. Signatures
- Backend command/API/DB signature(s)

### 3. Contracts
- Request fields (name, type, constraints)
- Response fields (name, type, constraints)
- Environment keys (required/optional)

### 4. Validation & Error Matrix
- <condition> -> <error>

### 5. Good/Base/Bad Cases
- Good: ...
- Base: ...
- Bad: ...

### 6. Tests Required
- Unit/Integration/E2E with assertion points

### 7. Wrong vs Correct
#### Wrong
...
#### Correct
...

Adding a Design Decision

### Design Decision: [Decision Name]

**Context**: What problem were we solving?

**Options Considered**:
1. Option A - brief description
2. Option B - brief description

**Decision**: We chose Option X because...

**Example**:
\`\`\`typescript
// How it's implemented
code example
\`\`\`

**Extensibility**: How to extend this in the future...

Adding a Project Convention

### Convention: [Convention Name]

**What**: Brief description of the convention.

**Why**: Why we do it this way in this project.

**Example**:
\`\`\`typescript
// How to follow this convention
code example
\`\`\`

**Related**: Links to related conventions or specs.

Adding a New Pattern

### Pattern Name

**Problem**: What problem does this solve?

**Solution**: Brief description of the approach.

**Example**:
\`\`\`
// Good
code example

// Bad
code example
\`\`\`

**Why**: Explanation of why this works better.

Adding a Forbidden Pattern

### Don't: Pattern Name

**Problem**:
\`\`\`
// Don't do this
bad code example
\`\`\`

**Why it's bad**: Explanation of the issue.

**Instead**:
\`\`\`
// Do this instead
good code example
\`\`\`

Adding a Common Mistake

### Common Mistake: Description

**Symptom**: What goes wrong

**Cause**: Why this happens

**Fix**: How to correct it

**Prevention**: How to avoid it in the future

Adding a Gotcha

> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.

Interactive Mode

If you're unsure what to update, answer these prompts:

  1. What did you just finish?

    • [ ] Fixed a bug
    • [ ] Implemented a feature
    • [ ] Refactored code
    • [ ] Had a discussion about approach
  2. What did you learn or decide?

    • Design decision (why X over Y)
    • Project convention (how we do X)
    • Non-obvious behavior (gotcha)
    • Better approach (pattern)
  3. Would future AI/developers need to know this?

    • To understand how the code works → Yes, update spec
    • To maintain or extend the feature → Yes, update spec
    • To avoid repeating mistakes → Yes, update spec
    • Purely one-off implementation detail → Maybe skip
  4. Which area does it relate to?

    • [ ] Backend code
    • [ ] Frontend code
    • [ ] Cross-layer data flow
    • [ ] Code organization/reuse
    • [ ] Quality/testing

Quality Checklist

Before finishing your code-spec update:

  • [ ] Is the content specific and actionable?
  • [ ] Did you include a code example?
  • [ ] Did you explain WHY, not just WHAT?
  • [ ] Did you include executable signatures/contracts?
  • [ ] Did you include validation and error matrix?
  • [ ] Did you include Good/Base/Bad cases?
  • [ ] Did you include required tests with assertion points?
  • [ ] Is it in the right code-spec file?
  • [ ] Does it duplicate existing content?
  • [ ] Would a new team member understand it?

Relationship to Other Commands

Development Flow:
  Learn something → `update-spec` (Trellis command) → Knowledge captured
       ↑                                  ↓
  `break-loop` (Trellis command) ←──────────────────── Future sessions benefit
  (deep bug analysis)
  • ``break-loop (Trellis command) - Analyzes bugs deeply, often reveals spec updates needed
  • ``update-spec (Trellis command) - Actually makes the updates
  • ``finish-work (Trellis command) - Reminds you to check if specs need updates

Core Philosophy

Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.

The goal is institutional memory:

  • What one person learns, everyone benefits from
  • What AI learns in one session, persists to future sessions
  • Mistakes become documented guardrails

Related Skills

View on GitHub
GitHub Stars1.2k
CategoryContent
Updated1mo ago
Forks135

Languages

Rust

Trust signals

88/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 medium