eryao/.claude/skills/trellis-meta/references/platform-files/skills-and-commands.md

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

1. Keep entry files short; references carry long content. This matters especially for multi-file skills like trellis-meta.
2. Make trigger descriptions specific. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
3. Keep the same semantics consistent across platforms. File formats can differ, but behavior descriptions should match.
4. 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.