Trellis 元技能：AI 开发平台兼容性指南与项目结构管理工具

trellis-meta by mindfold-ai/trellis

84 周安装量

4,000 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mindfold-ai/trellis --skill trellis-meta

AI/机器学习项目管理命令行工具

🇨🇳中文介绍

Trellis 元技能

版本兼容性

项目	值
Trellis CLI 版本	0.3.0
技能最后更新	2026-02-28
最低 Claude Code 版本	1.0.0+

⚠️ 版本不匹配警告：如果你的 Trellis CLI 版本与上述不同，某些功能可能无法按文档所述工作。运行 trellis --version 来检查。

平台兼容性

功能支持矩阵

功能	Claude Code	iFlow	Cursor	OpenCode	Codex

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

879,700 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

118,000 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

67,500 周安装

超能力技能使用指南：AI助手技能调用优先级与工作流程详解

50,500 周安装

┌─────────────────────────────────────────────────────────────┐
│                 可移植（所有 9 个平台）                      │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - 平台命令/技能                   │
│  - 基于文件的配置         - JSONL 上下文文件                │
└─────────────────────────────────────────────────────────────┘
                                  │
┌─────────────────────────────▼───────────────────────────────┐
│              支持钩子（Claude Code + iFlow）                 │
│  - .claude/hooks/ 或 .iflow/hooks/                          │
│  - settings.json 钩子配置                                   │
│  - 自动上下文注入          - SubagentStop 控制              │
│  - Ralph 循环              - 多会话工作树                   │
└─────────────────────────────────────────────────────────────┘

---
name: trellis-local
description: |
  [项目名称] 的 Trellis 项目特定定制。
  此技能记录了在此项目中对原始 Trellis 系统所做的修改。
  继承自 trellis-meta 以获取基础文档。
---

# Trellis 本地 - [项目名称]

## 基础版本

Trellis 版本：X.X.X（来自 package.json 或 trellis --version）
初始化日期：YYYY-MM-DD

## 定制

### 添加的命令

（尚无）

### 修改的智能体

（尚无）

### 更改的钩子

（尚无）

### 定制的规范

（尚无）

### 工作流更改

（尚无）

---

## 变更日志

### YYYY-MM-DD

- 初始设置

┌─────────────────────────────────────────────────────────────────────┐
│                        用户交互                                      │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel  /trellis:finish-work │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         技能层                                       │
│  .claude/commands/trellis/*.md   （斜杠命令）                       │
│  .claude/agents/*.md             （子智能体定义）                   │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          钩子层                                      │
│  SessionStart     → session-start.py （注入工作流 + 上下文）        │
│  PreToolUse:Task  → inject-subagent-context.py （规范注入）         │
│  SubagentStop     → ralph-loop.py （质量保证）                      │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       持久层                                         │
│  .trellis/workspace/  （日志、会话历史）                            │
│  .trellis/tasks/      （任务跟踪、上下文文件）                      │
│  .trellis/spec/       （编码指南）                                  │
└─────────────────────────────────────────────────────────────────────┘

原则	描述
规范注入，而非记忆	钩子强制执行规范——智能体始终接收上下文
先读后写	在编写代码前理解指南
分层上下文	仅加载相关规范（通过 JSONL 文件）
人工提交	AI 从不提交——人工首先验证
纯调度器	调度智能体仅负责编排

钩子	时机	目的
`SessionStart`	会话开始时	注入工作流、指南
`PreToolUse:Task`	子智能体使用前	通过 JSONL 注入规范
`SubagentStop:check`	检查智能体停止时	强制执行验证（Ralph 循环）

智能体	目的	限制
`dispatch`	编排流水线	纯调度器
`plan`	评估需求	可以拒绝不明确的需求
`research`	查找代码模式	只读
`implement`	编写代码	不能 git 提交
`check`	审查和自我修复	受 Ralph 循环控制
`debug`	修复问题	仅精确修复

创建带有 YAML 前置元数据的 .claude/agents/my-agent.md
更新 inject-subagent-context.py 以处理新的智能体类型
在任务目录中创建 my-agent.jsonl
更新 trellis-local 技能

文档	内容
`overview.md`	核心系统介绍
`files.md`	所有 `.trellis/` 文件及其用途
`workspace.md`	工作区系统、日志、开发者身份
`tasks.md`	任务系统、目录、JSONL 上下文文件
`specs.md`	规范系统、指南组织
`scripts.md`	平台无关脚本

文档	内容
`overview.md`	Claude Code 功能介绍
`hooks.md`	钩子系统、上下文注入
`agents.md`	智能体类型、调用、Task 工具
`ralph-loop.md`	质量保证机制
`multi-session.md`	并行工作树会话
`worktree-config.md`	worktree.yaml 配置
`scripts.md`	仅 Claude Code 脚本

文档	场景
`overview.md`	所有修改的快速参考
`add-command.md`	添加斜杠命令
`add-agent.md`	添加新智能体类型
`add-spec.md`	添加规范类别
`add-phase.md`	添加工作流阶段
`modify-hook.md`	修改钩子行为
`change-verify.md`	更改验证命令

文档	内容
`platform-compatibility.md`	详细的平台支持矩阵
`self-iteration-guide.md`	如何记录定制
`trellis-local-template.md`	项目本地技能模板

脚本	目的
`get_context.py`	获取会话上下文
`task.py`	任务管理
`add_session.py`	记录会话
`multi_agent/start.py`	启动并行智能体

路径	目的
`.trellis/.developer`	开发者身份标识
`.trellis/.current-task`	活动任务指针
`.trellis/workflow.md`	主要工作流文档
`.claude/settings.json`	钩子配置

🇺🇸English

Trellis Meta-Skill

Version Compatibility

Item	Value
Trellis CLI Version	0.3.0
Skill Last Updated	2026-02-28
Min Claude Code Version	1.0.0+

⚠️ Version Mismatch Warning : If your Trellis CLI version differs from above, some features may not work as documented. Run trellis --version to check.

Platform Compatibility

Feature Support Matrix

Feature	Claude Code	iFlow	Cursor	OpenCode	Codex	Kilo	Kiro	Gemini CLI	Antigravity
Core Systems
Workspace system	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full
Task system	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full
Spec system	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full	✅ Full

Legend

✅ Full : Feature works as documented
⚠️ Limited/Manual : Works but requires manual steps
❌ None/Manual : Not supported or requires manual workaround

Platform Categories

Full Hook Support (Claude Code, iFlow)

All features work as documented. Hooks provide automatic context injection and quality enforcement. iFlow shares the same Python hook system as Claude Code.

Commands Only (Cursor, OpenCode, Codex, Kilo, Kiro, Gemini CLI, Antigravity)

Works : Workspace, tasks, specs, commands/skills (platform-specific format)
Doesn't work : Hooks, auto-injection, Ralph Loop, Multi-Session
Workaround : Manually read spec files at session start; no automatic quality gates
Note : Each platform uses its own command format (Codex uses Skills, Gemini uses TOML, Antigravity uses Workflows)

Designing for Portability

When customizing Trellis, consider platform compatibility:

┌─────────────────────────────────────────────────────────────┐
│                 PORTABLE (All 9 Platforms)                   │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - Platform commands/skills        │
│  - File-based configs     - JSONL context files             │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              HOOK-CAPABLE (Claude Code + iFlow)              │
│  - .claude/hooks/ or .iflow/hooks/                          │
│  - settings.json hook configuration                         │
│  - Auto context injection   - SubagentStop control          │
│  - Ralph Loop               - Multi-Session worktrees       │
└─────────────────────────────────────────────────────────────┘

Purpose

This is the meta-skill for Trellis - it documents the original, unmodified Trellis system. When customizing Trellis for a specific project, record changes in a project-local skill (trellis-local), keeping this meta-skill as the authoritative reference for vanilla Trellis.

Skill Hierarchy

~/.claude/skills/
└── trellis-meta/              # THIS SKILL - Original Trellis documentation
                               # ⚠️ DO NOT MODIFY for project-specific changes

project/.claude/skills/
└── trellis-local/             # Project-specific customizations
                               # ✅ Record all modifications here

Why this separation?

User may have multiple projects with different Trellis customizations
Each project's trellis-local skill tracks ITS OWN modifications
The meta-skill remains clean as the reference for original Trellis
Enables easy upgrades: compare meta-skill with new Trellis version

Self-Iteration Protocol

When modifying Trellis for a project, follow this protocol:

1. Check for Existing Project Skill

# Look for project-local skill
ls -la .claude/skills/trellis-local/

2. Create Project Skill if Missing

If no trellis-local exists, create it:

mkdir -p .claude/skills/trellis-local

Then create .claude/skills/trellis-local/SKILL.md:

---
name: trellis-local
description: |
  Project-specific Trellis customizations for [PROJECT_NAME].
  This skill documents modifications made to the vanilla Trellis system
  in this project. Inherits from trellis-meta for base documentation.
---

# Trellis Local - [PROJECT_NAME]

## Base Version

Trellis version: X.X.X (from package.json or trellis --version)
Date initialized: YYYY-MM-DD

## Customizations

### Commands Added

(none yet)

### Agents Modified

(none yet)

### Hooks Changed

(none yet)

### Specs Customized

(none yet)

### Workflow Changes

(none yet)

---

## Changelog

### YYYY-MM-DD

- Initial setup

3. Record Every Modification

When making ANY change to Trellis, update trellis-local/SKILL.md:

Example: Adding a new command

### Commands Added

#### /trellis:my-command

- **File**: `.claude/commands/trellis/my-command.md`
- **Purpose**: [what it does]
- **Added**: 2026-01-31
- **Why**: [reason for adding]

Example: Modifying a hook

### Hooks Changed

#### inject-subagent-context.py

- **Change**: Added support for `my-agent` type
- **Lines modified**: 45-67
- **Date**: 2026-01-31
- **Why**: [reason]

4. Never Modify Meta-Skill for Project Changes

The trellis-meta skill should ONLY be updated when:

Trellis releases a new version
Fixing documentation errors in the original
Adding missing documentation for original features

Architecture Overview

Trellis transforms AI assistants into structured development partners through enforced context injection.

System Layers

┌─────────────────────────────────────────────────────────────────────┐
│                        USER INTERACTION                              │
│  /trellis:start  /trellis:brainstorm  /trellis:parallel  /trellis:finish-work │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (slash commands)                   │
│  .claude/agents/*.md             (sub-agent definitions)            │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart     → session-start.py (injects workflow + context)   │
│  PreToolUse:Task  → inject-subagent-context.py (spec injection)     │
│  SubagentStop     → ralph-loop.py (quality enforcement)             │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files)                │
│  .trellis/spec/       (coding guidelines)                           │
└─────────────────────────────────────────────────────────────────────┘

Key Design Principles

Principle	Description
Specs Injected, Not Remembered	Hooks enforce specs - agents always receive context
Read Before Write	Understand guidelines before writing code
Layered Context	Only relevant specs load (via JSONL files)
Human Commits	AI never commits - human validates first
Pure Dispatcher	Dispatch agent only orchestrates

Core Components

1. Workspace System

Track development progress across sessions with per-developer isolation.

.trellis/workspace/
├── index.md                    # Global overview
└── {developer}/                # Per-developer
    ├── index.md                # Personal index (@@@auto markers)
    └── journal-N.md            # Session journals (max 2000 lines)

Key files : .trellis/.developer (identity), journals (session history)

2. Task System

Track work items with phase-based execution.

.trellis/tasks/{MM-DD-slug-assignee}/
├── task.json           # Metadata, phases, branch
├── prd.md              # Requirements
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
└── debug.jsonl         # Context for debug agent

3. Spec System

Maintain coding standards that get injected to agents.

.trellis/spec/
├── frontend/           # Frontend guidelines
├── backend/            # Backend guidelines
└── guides/             # Thinking guides

4. Hooks System

Automatically inject context and enforce quality.

Hook	When	Purpose
`SessionStart`	Session begins	Inject workflow, guidelines
`PreToolUse:Task`	Before sub-agent	Inject specs via JSONL
`SubagentStop:check`	Check agent stops	Enforce verification (Ralph Loop)

5. Agent System

Specialized agents for different phases.

Agent	Purpose	Restriction
`dispatch`	Orchestrate pipeline	Pure dispatcher
`plan`	Evaluate requirements	Can reject unclear reqs
`research`	Find code patterns	Read-only
`implement`	Write code	No git commit
`check`	Review and self-fix	Ralph Loop controlled

6. Multi-Agent Pipeline

Run parallel isolated sessions via Git worktrees.

plan.py → start.py → Dispatch → implement → check → create-pr

Customization Guide

Adding a Command

Create .claude/commands/trellis/my-command.md
Update trellis-local skill with the change

Adding an Agent

Create .claude/agents/my-agent.md with YAML frontmatter
Update inject-subagent-context.py to handle new agent type
Create my-agent.jsonl in task directories
Update trellis-local skill

Modifying Hooks

Edit the hook script in .claude/hooks/
Document the change in trellis-local skill
Note which lines were modified and why

Extending Specs

Create new category in .trellis/spec/my-category/
Add index.md and guideline files
Reference in JSONL context files
Update trellis-local skill

Changing Task Workflow

Modify next_action array in task.json
Update dispatch or hook scripts as needed
Document in trellis-local skill

Resources

Reference documents are organized by platform compatibility:

references/
├── core/              # All Platforms (Claude Code, Cursor, etc.)
├── claude-code/       # Claude Code Only
├── how-to-modify/     # Modification Guides
└── meta/              # Documentation & Templates

`core/` - All Platforms

Document	Content
`overview.md`	Core systems introduction
`files.md`	All `.trellis/` files with purposes
`workspace.md`	Workspace system, journals, developer identity
`tasks.md`	Task system, directories, JSONL context files
`specs.md`	Spec system, guidelines organization
`scripts.md`

`claude-code/` - Claude Code Only

Document	Content
`overview.md`	Claude Code features introduction
`hooks.md`	Hook system, context injection
`agents.md`	Agent types, invocation, Task tool
`ralph-loop.md`	Quality enforcement mechanism
`multi-session.md`	Parallel worktree sessions
`worktree-config.md`	worktree.yaml configuration

`how-to-modify/` - Modification Guides

Document	Scenario
`overview.md`	Quick reference for all modifications
`add-command.md`	Adding slash commands
`add-agent.md`	Adding new agent types
`add-spec.md`	Adding spec categories
`add-phase.md`	Adding workflow phases
`modify-hook.md`	Modifying hook behavior

`meta/` - Documentation

Document	Content
`platform-compatibility.md`	Detailed platform support matrix
`self-iteration-guide.md`	How to document customizations
`trellis-local-template.md`	Template for project-local skill

Quick Reference

Key Scripts

Script	Purpose
`get_context.py`	Get session context
`task.py`	Task management
`add_session.py`	Record session
`multi_agent/start.py`	Start parallel agent

Key Paths

Path	Purpose
`.trellis/.developer`	Developer identity
`.trellis/.current-task`	Active task pointer
`.trellis/workflow.md`	Main workflow docs
`.claude/settings.json`	Hook configuration

Upgrade Protocol

When upgrading Trellis to a new version:

Compare new meta-skill with current
Review changes in new version
Check trellis-local for conflicts
Merge carefully, preserving customizations
Update trellis-local with migration notes

## Changelog

### 2026-02-01 - Upgraded to Trellis X.Y.Z

- Merged new hook behavior from meta-skill
- Kept custom agent `my-agent`
- Updated check.jsonl template

Weekly Installs

Repository

mindfold-ai/trellis

GitHub Stars

4.0K

First Seen

Feb 10, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykWarn

Installed on

codex81

gemini-cli80

amp80

kimi-cli80

github-copilot80

opencode80

核心系统
工作区系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
任务系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
规范系统	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 完整
命令/技能	✅ 完整	✅ 完整	✅ 完整	✅ 完整	✅ 技能	✅ 完整	✅ 技能	✅ TOML	✅ 工作流
智能体定义	✅ 完整	✅ 完整	⚠️ 手动	✅ 完整	⚠️ 手动	⚠️ 手动	⚠️ 手动	⚠️ 手动	⚠️ 手动
钩子依赖功能
SessionStart 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
PreToolUse 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
SubagentStop 钩子	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
自动上下文注入	✅ 完整	✅ 完整	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动	❌ 手动
Ralph 循环	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无
多智能体/会话
多智能体（当前目录）	✅ 完整	✅ 完整	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限	⚠️ 有限
多会话（工作树）	✅ 完整	✅ 完整	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无	❌ 无

Trellis 元技能：AI 开发平台兼容性指南与项目结构管理工具

🇨🇳中文介绍

Trellis 元技能

版本兼容性

平台兼容性

功能支持矩阵

相关 Skills

图例

平台类别

完整钩子支持（Claude Code, iFlow）

仅命令支持（Cursor, OpenCode, Codex, Kilo, Kiro, Gemini CLI, Antigravity）

可移植性设计

目的

技能层次结构

自我迭代协议

1. 检查是否存在项目技能

2. 创建项目技能（如果缺失）

3. 记录每次修改

示例：添加新命令

示例：修改钩子

4. 切勿为项目更改修改元技能

架构概述

系统层级

关键设计原则

核心组件

1. 工作区系统

2. 任务系统

3. 规范系统

4. 钩子系统

5. 智能体系统

6. 多智能体流水线

定制指南

添加命令

添加智能体

修改钩子

扩展规范

更改任务工作流

资源

core/ - 所有平台

claude-code/ - 仅 Claude Code

how-to-modify/ - 修改指南

meta/ - 文档

快速参考

关键脚本

关键路径

升级协议