3.8 KiB
Skills, Commands, Prompts, And Workflows
Skills and commands are textual entry points for user interaction with Trellis. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the Trellis flow when the user expresses a certain intent.
Conceptual Differences
| Type | Trigger mode | Best for |
|---|---|---|
| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
Trellis workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as trellis-meta use layered references.
Common Paths
| Platform | Common entries |
|---|---|
| Claude Code | .claude/skills/, .claude/commands/ |
| Cursor | .cursor/skills/, .cursor/commands/ |
| OpenCode | .opencode/skills/, .opencode/commands/ |
| Codex | .agents/skills/, .codex/skills/ |
| Kilo | .kilocode/skills/, .kilocode/workflows/ |
| Kiro | .kiro/skills/ |
| Gemini CLI | .agents/skills/, .gemini/commands/ |
| Antigravity | .agent/skills/, .agent/workflows/ |
| Windsurf | .windsurf/skills/, .windsurf/workflows/ |
| Qoder | .qoder/skills/, .qoder/commands/ |
| CodeBuddy | .codebuddy/skills/, .codebuddy/commands/ |
| GitHub Copilot | .github/skills/, .github/prompts/ |
| Factory Droid | .factory/skills/, .factory/commands/ |
| Pi Agent | .pi/skills/ |
In a user project, use the files actually generated by init as authoritative.
Skill Structure
A common skill is a directory:
trellis-meta/
├── SKILL.md
└── references/
SKILL.md should tell the AI:
- When to use this skill.
- Which reference to read first for the current task.
- What not to do.
References hold longer explanations so the entry file does not contain everything.
Command/Prompt/Workflow Structure
Commands, prompts, and workflows are usually single files. Their content should include:
- When to use it.
- Which
.trellis/files to read. - Which scripts to run.
- How to report after completion.
They should not store task state; task state belongs in .trellis/tasks/ and .trellis/.runtime/.
Local Change Scenarios
| User need | Edit location |
|---|---|
| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
| Change user command behavior | The corresponding command/prompt/workflow file. |
| Add a project-local skill | Platform skill directory, or shared .agents/skills/. |
| Let multiple platforms share one capability | Write equivalent skills in each platform skill directory, or use the .agents/skills/ shared layer on platforms that support it. |
| Change finish/continue entry points | Platform commands/prompts/workflows. |
Modification Principles
- Keep entry files short; references carry long content. This matters especially for multi-file skills like
trellis-meta. - Make trigger descriptions specific. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
- Keep the same semantics consistent across platforms. File formats can differ, but behavior descriptions should match.
- Put project-specific capabilities in local skills. Do not put team-private flows into public
trellis-meta.
If the user only wants local AI to know one more project rule, usually create a project-local skill or update .trellis/spec/ instead of changing a Trellis built-in workflow skill.