zl-q
04b493ed09
- Remove legacy .opencode/ directory and configuration - Update .trellis/ to v0.5.0-rc.6 structure - Refactor scripts: modularize common/, remove multi_agent/ - Add new common modules: git.py, io.py, log.py, types.py, etc. - Update workflow.md and AGENTS.md - Archive completed migration tasks
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# 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.
|