Agent skill

Trellis Update Spec

by anjiemo in anjiemo/SunnyBeach

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

Apache-2.0Auto-check passedDevelopment

Install Trellis Update Spec

skills CLI
$ npx skills add anjiemo/SunnyBeach --skill trellis-update-spec -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install anjiemo/SunnyBeach trellis-update-spec --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/anjiemo/SunnyBeach.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/trellis-update-spec .claude/skills/trellis-update-spec && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
trellis-update-spec
GitHub stars
178
Used in
7 other repos
Token cost
~2.8k tokens
SKILL.md length
915 words
Files
1
Skills in repo
7
Repo updated
First seen
Licence
Apache-2.0

At a glance

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

  • Works in 5 steps: Identify What You Learned → Classify the Update Type → Read the Target Code-Spec → …
  • Learning something valuable from debugging
  • SKILL.md covers Code-Spec First Rule (CRITICAL), When to Update Code-Specs, Spec Structure Overview and Update Process, plus 5 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Trellis Update Spec is an agent skill from anjiemo/SunnyBeach. 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.

Its SKILL.md is about 2.8k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. The repository describes itself as: 这是一款基于 Kotlin、MVVM 和 Jetpack 构建的【阳光沙滩】社区开源Android客户端。我们的使命是让编程学习更简单,欢迎贡献!. The licence is Apache-2.0.

When your agent uses it

  • Learning something valuable from debugging
  • Discussion that should be preserved for future sessions

Example prompts

  • “Use the trellis-update-spec skill to capture executable contracts and coding conventions into .trellis/spec/ documents”
  • “/trellis-update-spec”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Identify What You Learned
  2. Classify the Update Type
  3. Read the Target Code-Spec
  4. Make the Update
  5. Update the Index (if needed)

What it can do on your machine

Read from SKILL.md and the folder at commit ec2bf56. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Trellis Update Spec loads about 2.8k tokens when it runs. Until then it costs about 58 tokens; SKILL.md has 915 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~58
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from anjiemo/SunnyBeach at commit ec2bf56, republished under its Apache-2.0 licence (© anjiemo). 915 words, ~2,756 tokens.

Download SKILL.mdSave it as .claude/skills/trellis-update-spec/SKILL.md (or your agent's skills folder).
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

TriggerExampleTarget Spec
Implemented a featureAdded a new integration or moduleRelevant spec file
Made a design decisionChose extensibility pattern over simplicityRelevant spec + "Design Decisions" section
Fixed a bugFound a subtle issue with error handlingRelevant spec (e.g., error-handling docs)
Discovered a patternFound a better way to structure codeRelevant spec file
Hit a gotchaLearned that X must be done before YRelevant spec + "Common Mistakes" section
Established a conventionTeam agreed on naming patternQuality 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
TypeLocationPurposeContent Style
Code-Spec<layer>/*.mdTell AI "how to implement safely"Signatures, contracts, matrices, cases, test points
Guideguides/*.mdHelp 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:

LearningWrong LocationCorrect 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
TypeDescriptionAction
Design DecisionWhy we chose approach X over YAdd to "Design Decisions" section
Project ConventionHow we do X in this projectAdd to relevant section with examples
New PatternA reusable approach discoveredAdd to "Patterns" section
Forbidden PatternSomething that causes problemsAdd to "Anti-patterns" or "Don't" section
Common MistakeEasy-to-make errorAdd to "Common Mistakes" section
ConventionAgreed-upon standardAdd to relevant section
GotchaNon-obvious behaviorAdd 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
bash
cat .trellis/spec/<category>/<file>.md
Show full SKILL.md (366 more words)Show less
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
markdown
## 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
markdown
### 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
markdown
### 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
markdown
### 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
markdown
### 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
markdown
### 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
markdown
> **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

© anjiemo, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .agents/skills/trellis-update-spec of anjiemo/SunnyBeach.

Open the folder on GitHubat commit ec2bf56

Used in 7 other repositories

We found 25 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 7 other GitHub owners. This page covers the copy in anjiemo/SunnyBeach, which our catalogue first saw on October 7, 2026.

Compare with similar skills

Trellis Update Spec next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Trellis Update Spec compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Trellis Update Spec this skillanjiemo/SunnyBeach1787 repos~2.8kAutomated safety check: PassApache-2.0
Vercel Composition Patternssupabase/supabase111k58 repos~726Automated safety check: PassMIT
Finishing a Development Branchobra/superpowers297k5 repos~1.9kAutomated safety check: PassMIT
Typescript Advanced Typesrolling-scopes/rsschool-app10k25 repos~4.2kAutomated safety check: PassMPL-2.0
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Code Review ChecklistshareAI-lab/learn-claude-code78k5 repos~1.1kAutomated safety check: PassMIT

Similar skills

  • Official

    React composition patterns that scale. An agent skill from supabase/supabase.

    111k GitHub starsUsed in 58 repos~726 tokens
    DevelopmentAuto-check passed
  • Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    297k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed
  • Typescript Advanced Types

    rolling-scopes/rsschool-app

    Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.

    10k GitHub starsUsed in 25 repos~4.2k tokens
    DevelopmentAuto-check passed
  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed
  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 5 repos~1.1k tokens
    DevelopmentAuto-check passed
  • Greploop

    onyx-dot-app/onyx

    Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.

    32k GitHub starsUsed in 4 repos~3.3k tokens
    DevelopmentAuto-check passed

More from anjiemo/SunnyBeach

  • Trellis Brainstorm

    anjiemo/SunnyBeach

    Guides collaborative requirements discovery before implementation.

    178 GitHub starsUsed in 7 repos~4k tokens
    Auto-check passed
  • Trellis Check

    anjiemo/SunnyBeach

    Comprehensive quality verification: spec compliance, lint, type-check, tests, cross-layer data flow, code reuse, and consistency checks.

    178 GitHub starsUsed in 7 repos~666 tokens
    Auto-check passed
  • Trellis Spec Bootstarp

    anjiemo/SunnyBeach

    Bootstrap project-specific Trellis coding specs with a platform-neutral single-agent workflow.

    178 GitHub starsUsed in 7 repos~740 tokens
    Auto-check passed
  • Trellis Break Loop

    anjiemo/SunnyBeach

    Deep bug analysis to break the fix-forget-repeat cycle. An agent skill from anjiemo/SunnyBeach.

    178 GitHub starsUsed in 7 repos~1.3k tokens
    Auto-check passed
  • Trellis Before Dev

    anjiemo/SunnyBeach

    Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins.

    178 GitHub starsUsed in 7 repos~398 tokens
    Auto-check passed
  • Trellis Meta

    anjiemo/SunnyBeach

    Understand and customize the local Trellis architecture inside a user project.

    178 GitHub starsUsed in 2 repos~1.4k tokens
    Auto-check passed

Categories

Questions about Trellis Update Spec

What does Trellis Update Spec do?

Captures executable contracts and coding conventions into .trellis/spec/ documents. Trellis Update Spec is an agent skill from anjiemo/SunnyBeach.trellis/spec/ documents.

When should I use Trellis Update Spec?

Trellis Update Spec fits situations like: learning something valuable from debugging; discussion that should be preserved for future sessions.

How do I install Trellis Update Spec in Claude Code?

Run `npx skills add anjiemo/SunnyBeach --skill trellis-update-spec -a claude-code`. Or copy the skill folder (.agents/skills/trellis-update-spec in anjiemo/SunnyBeach) into .claude/skills/trellis-update-spec in your project. Claude Code loads it when a task matches its description.

How do I install Trellis Update Spec in Codex?

Run `npx skills add anjiemo/SunnyBeach --skill trellis-update-spec -a codex`. Or copy the skill folder (.agents/skills/trellis-update-spec in anjiemo/SunnyBeach) into .agents/skills/trellis-update-spec in your project. Codex loads it when a task matches its description.

Can I use Trellis Update Spec in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add anjiemo/SunnyBeach --skill trellis-update-spec -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/trellis-update-spec, .gemini/skills/trellis-update-spec, .github/skills/trellis-update-spec and .opencode/skills/trellis-update-spec in your project.

What does Trellis Update Spec need to run?

SKILL.md names no scripts, command-line tools or credentials: Trellis Update Spec is instructions for the agent only.

Does Trellis Update Spec access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Trellis Update Spec safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Trellis Update Spec use?

Trellis Update Spec is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Trellis Update Spec use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Trellis Update Spec?

Skills that share tags, products or a category with Trellis Update Spec: Vercel Composition Patterns (supabase/supabase, 111k stars), Finishing a Development Branch (obra/superpowers, 297k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars) and PR Babysitter (openinterpreter/openinterpreter, 69k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Trellis Update Spec?

anjiemo (a GitHub user) maintains it in anjiemo/SunnyBeach, which has 178 GitHub stars. The repository holds 7 skills in this directory. The repository was last updated on September 11, 2026.

Source: anjiemo/SunnyBeach on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.