explainx.ainewsletter3.4k
Productivity

trellis-meta▌

mindfold-ai/trellis · updated Apr 8, 2026

MDX-style export adds YAML metadata + attribution linking explainx.ai and this canonical listing URL.

$npx skills add https://github.com/mindfold-ai/trellis --skill trellis-meta
0 commentsdiscussion
summary

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

skill.md

Trellis Meta-Skill

Version Compatibility

Item Value
Trellis CLI Version 0.4.0-beta.8
Skill Last Updated 2026-03-24
Min Claude Code Version 1.0.0+
Min Node.js Version >=18.17.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 Qoder CodeBuddy
Core Systems
Workspace system ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full
Task system ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full
Spec system ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full ✅ Full
Commands/Skills ✅ Full ✅ Full ✅ Full ✅ Full ✅ Skills ✅ Full ✅ Skills ✅ TOML ✅ Workflows ✅ Skills ✅ Full
Agent definitions ✅ Full ✅ Full ⚠️ Manual ✅ Full ✅ TOML ⚠️ Manual ⚠️ Manual ⚠️ Manual ⚠️ Manual ⚠️ Manual ⚠️ Manual
Shared agent skills — — — — ✅ Full — — — — — —
Hook-Dependent Features
SessionStart hook ✅ Full ✅ Full ❌ None ❌ None ⚠️ Optional ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None
PreToolUse hook ✅ Full ✅ Full ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None
SubagentStop hook ✅ Full ✅ Full ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None
Auto context injection ✅ Full ✅ Full ❌ Manual ❌ Manual ❌ Manual ❌ Manual ❌ Manual ❌ Manual ❌ Manual ❌ Manual ❌ Manual
Ralph Loop ✅ Full ✅ Full ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None
Multi-Agent/Session
Multi-Agent (current dir) ✅ Full ✅ Full ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited ⚠️ Limited
Multi-Session (worktrees) ✅ Full ✅ Full ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None ❌ None

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.

Partial Hook Support (Codex)

  • Works: Workspace, tasks, specs, skills (.codex/skills/ + .agents/skills/ shared layer), TOML agent definitions (.codex/agents/), optional SessionStart hook
  • Doesn't work: PreToolUse, SubagentStop, Ralph Loop, Multi-Session
  • Note: SessionStart hook requires codex_hooks = true in ~/.codex/config.toml

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

  • 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 (Kiro/Qoder use Skills, Gemini uses TOML, Antigravity uses Workflows, CodeBuddy uses nested Markdown commands)

Designing for Portability

When customizing Trellis, consider platform compatibility:

┌─────────────────────────────────────────────────────────────┐
│                 PORTABLE (All 11 Platforms)                  │
│  - .trellis/workspace/    - .trellis/tasks/                 │
│  - .trellis/spec/         - Platform commands/skills        │
│  - File-based configs     - JSONL context files             │
│  - config.yaml            - Monorepo packages support       │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│         SHARED AGENT SKILLS (agentskills.io standard)       │
│  - .agents/skills/          (Codex + universal agent CLIs)  │
└─────────────────────────────┬───────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────┐
│              HOOK-CAPABLE (Claude Code + iFlow)              │
│  - .claude/hooks/ or .iflow/hooks/                          │
│  - settings.json hook configuration                         │
│  - Auto context injection   - SubagentStop control          │
│  - Ralph Loop               - Multi-Session worktrees       │
│  - Task lifecycle hooks     - Dynamic spec discovery        │
└─────────────────────────────────────────────────────────────┘

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  /trellis:before-dev  /trellis:check          │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                         SKILLS LAYER                                 │
│  .claude/commands/trellis/*.md   (17 slash commands)                │
│  .claude/agents/*.md             (6 sub-agent definitions)          │
│  .agents/skills/*/SKILL.md       (shared agent skills layer)        │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                          HOOKS LAYER                                 │
│  SessionStart      → session-start.py (workflow + context + status) │
│  PreToolUse:Agent  → inject-subagent-context.py (spec injection)    │
│  SubagentStop      → ralph-loop.py (quality enforcement)            │
│  Task Lifecycle    → config.yaml hooks (after_create/start/finish/  │
│                      archive → e.g. Linear sync)                    │
└─────────────────────────────────┬───────────────────────────────────┘
                                  │
┌─────────────────────────────────▼───────────────────────────────────┐
│                       PERSISTENCE LAYER                              │
│  .trellis/workspace/  (journals, session history)                   │
│  .trellis/tasks/      (task tracking, context files, subtasks)      │
│  .trellis/spec/       (coding guidelines, monorepo per-package)     │
│  .trellis/config.yaml (packages, hooks, update.skip, spec_scope)   │
└─────────────────────────────────────────────────────────────────────┘

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, parent-child subtasks, and lifecycle hooks.

.trellis/tasks/{MM-DD-slug}/
├── task.json           # Metadata, phases, branch, subtasks
├── prd.md              # Requirements
├── info.md             # Technical design (optional)
├── implement.jsonl     # Context for implement agent
├── check.jsonl         # Context for check agent
├── debug.jsonl         # Context for debug agent
├── research.jsonl      # Context for research agent (optional)
└── cr.jsonl            # Context for code review (optional)

3. Spec System

Maintain coding standards that get injected to agents. Supports both single-repo and monorepo layouts.

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

# Monorepo (per-package)
.trellis/spec/
how to use trellis-meta

How to use trellis-meta on Cursor

AI-first code editor with Composer

1

Prerequisites

Before installing skills in Cursor, ensure your development environment meets these requirements:

  • ›Cursor installed and configured on your development machine
  • ›Node.js version 16.0+ with npm package manager (verify with node --version)
  • ›Active project directory or workspace where you want to add trellis-meta
2

Execute installation command

Execute the skills CLI command in your project's root directory to begin installation:

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

The skills CLI fetches trellis-meta from GitHub repository mindfold-ai/trellis and configures it for Cursor.

3

Select Cursor when prompted

The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:

◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│ • Amp
│ • Antigravity
│ • Cline
│ • Codex
│ ●Cursor(selected)
│ • Cursor
│ • Windsurf
4

Verify installation

Confirm successful installation by checking the skill directory location:

.cursor/skills/trellis-meta

Reload or restart Cursor to activate trellis-meta. Access the skill through slash commands (e.g., /trellis-meta) or your agent's skill management interface.

⚠

Security & Verification Notice

We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.

Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.

Additional Resources

›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?

List & Monetize Your Skill

Submit your Claude Code skill and start earning

GET_STARTED →

Use Cases▌

User Story & Requirements Generation

Create detailed user stories, acceptance criteria, and feature specs

Example

Generate user stories for 'password reset feature' with acceptance criteria, edge cases, and test scenarios

✓

Reduce spec writing time by 50%, ensure comprehensive coverage

Competitive Analysis

Research competitors, compare features, identify gaps

Example

Analyze 5 competitor products, create feature comparison matrix, suggest differentiation opportunities

✓

Complete competitive research in 2 hours instead of 2 days

Roadmap Prioritization

Evaluate features using frameworks (RICE, ICE, Kano) and create prioritized backlogs

Example

Score 20 feature ideas using RICE framework, generate prioritized roadmap with rationale

✓

Make data-driven prioritization decisions faster

Stakeholder Communication

Draft PRDs, status updates, and stakeholder presentations

Example

Create executive summary of Q3 roadmap, monthly progress report, feature launch announcement

✓

Save 3-5 hours/week on communication overhead

Implementation Guide▌

Prerequisites

  • ›Claude Desktop or compatible AI client
  • ›Access to product documentation and roadmap tools (Jira, Notion, etc.)
  • ›Understanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
  • ›Stakeholder contact information and communication channels

Time Estimate

30-60 minutes to see productivity improvements

Installation Steps

  1. 1.Install product management skill
  2. 2.Start with user story generation for known feature
  3. 3.Progress to competitive analysis: research 2-3 competitors
  4. 4.Use for roadmap prioritization: apply RICE/ICE scoring
  5. 5.Draft stakeholder communications and refine based on feedback
  6. 6.Build template library for recurring PM tasks
  7. 7.Share effective prompts with product team

Common Pitfalls

  • ⚠Not validating competitive research—verify facts before sharing
  • ⚠Accepting user stories without involving engineering team
  • ⚠Over-relying on frameworks without qualitative judgment
  • ⚠Not customizing outputs to company culture and communication style
  • ⚠Skipping stakeholder validation of generated requirements

Best Practices▌

✓ Do

  • +Validate research and competitive analysis with real data
  • +Collaborate with engineering when generating technical requirements
  • +Customize frameworks and templates to your company context
  • +Use skill for first drafts, refine with stakeholder input
  • +Document successful prompt patterns for PM tasks
  • +Combine AI efficiency with human judgment and intuition

✗ Don't

  • −Don't publish competitive analysis without fact-checking
  • −Don't finalize user stories without engineering review
  • −Don't make prioritization decisions solely on AI scoring
  • −Don't skip customer validation of generated requirements
  • −Don't ignore company-specific context and culture

💡 Pro Tips

  • ★Provide context: company goals, constraints, customer feedback
  • ★Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
  • ★Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
  • ★Use skill for 70% generation + 30% customization to company needs

When to Use This▌

✓ Use When

Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.

✗ Avoid When

Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.

Learning Path▌

  1. 1Basic: user stories, feature specs, status updates
  2. 2Intermediate: competitive analysis, prioritization frameworks, PRDs
  3. 3Advanced: product strategy, go-to-market planning, OKR setting
  4. 4Expert: product vision, market positioning, business model innovation

Discussion

Product Hunt–style comments (not star reviews)
  • No comments yet — start the thread.
general reviews

Ratings

4.8★★★★★56 reviews
  • ★★★★★Amina Diallo· Dec 28, 2024

    Keeps context tight: trellis-meta is the kind of skill you can hand to a new teammate without a long onboarding doc.

  • ★★★★★Nikhil Rahman· Dec 28, 2024

    trellis-meta fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.

  • ★★★★★Liam Harris· Dec 24, 2024

    I recommend trellis-meta for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.

  • ★★★★★Pratham Ware· Dec 16, 2024

    trellis-meta has been reliable in day-to-day use. Documentation quality is above average for community skills.

  • ★★★★★Tariq Mensah· Dec 16, 2024

    Registry listing for trellis-meta matched our evaluation — installs cleanly and behaves as described in the markdown.

  • ★★★★★Sakura Abebe· Dec 4, 2024

    Useful defaults in trellis-meta — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.

  • ★★★★★Naina Khan· Dec 4, 2024

    trellis-meta has been reliable in day-to-day use. Documentation quality is above average for community skills.

  • ★★★★★Naina Nasser· Nov 23, 2024

    I recommend trellis-meta for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.

  • ★★★★★Diego Gonzalez· Nov 19, 2024

    We added trellis-meta from the explainx registry; install was straightforward and the SKILL.md answered most questions upfront.

  • ★★★★★Mei Smith· Nov 15, 2024

    Useful defaults in trellis-meta — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.

showing 1-10 of 56

1 / 6