- name
SKILL.md
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add fy-agent/fyagent --skill trellis-update-spec -a cursor -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add fy-agent/fyagent --skill trellis-update-spec -a claude-code -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add fy-agent/fyagent --skill trellis-update-spec -a codex -yPaste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add fy-agent/fyagent --skill trellis-update-spec -a grok -ySend the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
Install this skill: https://github.com/fy-agent/fyagent/tree/HEAD/.agents/skills/trellis-update-specFrom the publisher
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
In this project, "spec" for implementation work means code-spec:
If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
Apply code-spec depth when the change includes any of:
For triggered tasks, include all sections below:
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.
.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
Decision Rule: Ask yourself:
guides/Example:
Guides should be short checklists that point to specs, not duplicate the detailed rules.
Answer these questions:
Before editing, read the current code-spec to:
cat .trellis/spec/<category>/<file>.md
Follow these principles:
If you added a new section or the code-spec status changed, update the category's index.md.
## 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
...
### 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...
### 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.
### 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.
### 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
\`\`\`
### Common Mistake: Description
**Symptom**: What goes wrong
**Cause**: Why this happens
**Fix**: How to correct it
**Prevention**: How to avoid it in the future
> **Warning**: Brief description of the non-obvious behavior.
>
> Details about when this happens and how to handle it.
If you're unsure what to update, answer these prompts:
What did you just finish?
What did you learn or decide?
Would future AI/developers need to know this?
Which area does it relate to?
Before finishing your code-spec update:
Development Flow:
Learn something → `update-spec` (Trellis command) → Knowledge captured
↑ ↓
`break-loop` (Trellis command) ←──────────────────── Future sessions benefit
(deep bug analysis)
(Trellis command) - Analyzes bugs deeply, often reveals spec updates needed (Trellis command) - Actually makes the updates (Trellis command) - Reminds you to check if specs need updatesCode-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.
The goal is institutional memory:
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
---name: trellis-update-specdescription: Captures executable contracts and coding conventions into .trellis/spec/ documents. Use when learning…---# .agents/skills/trellis-update-spec/SKILL.mdOverview
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.
FAQ
Download .agents/skills/trellis-update-spec/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
The publisher keeps it at https://github.com/fy-agent/fyagent.
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.