# 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:

```text
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.