Custom Skills

Skills are the primary extension point in Trellis. Most of the shipped workflow (brainstorm, before-dev, check, update-spec, break-loop) is delivered as auto-trigger skills. This chapter explains how to add your own.

Commands vs. sub-agents vs. skills

	Command	Sub-agent	Skill
Purpose	Explicit user entry point	Isolated sub-process for a role	Reusable workflow module
Trigger	`/trellis:xxx`	Spawned via Task tool	Platform auto-matches on user intent
Granularity	Session boundary	Role-level	Capability or phase level
Cross-platform	One file per platform	One file per platform	One folder per platform (same structure)

Use a skill when the AI should trigger it automatically based on context; use a command when the user should decide; use a sub-agent when the work needs isolation with its own prompt and restrictions.

Skill file format

A skill is a folder containing SKILL.md:

.claude/skills/my-skill/
├── SKILL.md
└── references/         # optional supporting files the skill can reference

SKILL.md uses YAML frontmatter that the platform matches against:

---
name: my-skill
description: |
  One-line description of when this skill should fire. Platforms match on this text to decide whether to auto-trigger.
---

# My Skill

Instructions the AI follows when this skill is triggered.

## Steps

1. Read the relevant files.
2. Apply the logic.
3. Report the result in this format: ...

Skills ship on all 21 configured platforms — the location differs per platform:

Platform	Location
Claude Code	`.claude/skills/{name}/SKILL.md`
Cursor	`.cursor/skills/{name}/SKILL.md`
OpenCode	`.opencode/skills/{name}/SKILL.md`
Codex	`.agents/skills/{name}/SKILL.md` (shared layer; `.codex/skills/` is created empty for your own skills)
Kiro	`.kiro/skills/{name}/SKILL.md`
Gemini CLI	`.agents/skills/{name}/SKILL.md` (Gemini CLI 0.40+ reads the shared layer)
Qoder	`.qoder/skills/{name}/SKILL.md`
CodeBuddy	`.codebuddy/skills/{name}/SKILL.md`
Copilot	`.github/skills/{name}/SKILL.md`
Droid	`.factory/skills/{name}/SKILL.md`
Pi Agent	`.agents/skills/{name}/SKILL.md` (Pi reads the shared layer)
Oh My Pi	`.omp/skills/{name}/SKILL.md`
Kilo	`.kilocode/skills/{name}/SKILL.md`
Antigravity	`.agent/skills/{name}/SKILL.md`
Devin	`.devin/skills/{name}/SKILL.md`
Reasonix	`.reasonix/skills/{name}/SKILL.md`
ZCode	`.zcode/skills/{name}/SKILL.md`
Trae	`.trae/skills/{name}/SKILL.md`
Grok Build	`.grok/skills/{name}/SKILL.md`
Kimi Code	`.kimi-code/skills/{name}/SKILL.md`
Snow CLI	`.snow/skills/{name}/SKILL.md`

.agents/skills/{name}/SKILL.md (the agentskills.io cross-platform shared layer) is directly usable by Amp, Cline, Deep Agents, Firebender, Warp, and other agents that read the standard.

Writing a skill that triggers reliably

The description field is what platforms match on. Write it as a description of the condition that should cause this skill to fire, not a description of the skill’s name. Examples:

# Good: describes the trigger
description: |
  Use when the user reports a bug that was just fixed and wants to understand the root cause and prevent recurrence. Runs a 5-dimension analysis.

# Bad: describes the skill's identity
description: |
  The break-loop skill analyzes bugs.

The skill body should:

State the trigger condition again, in the skill’s own voice, so the AI can double-check that the match was correct.
Tell the AI exactly which files to read before acting.
Give a fixed output format so the result is consistent across invocations.

Example: an `api-doc` skill

.claude/skills/api-doc/SKILL.md:

---
name: api-doc
description: |
  Use when the user has just added or modified backend API endpoints and wants the OpenAPI doc updated. Parses the diff, extracts endpoint signatures, and writes the doc.
---

# api-doc

You auto-generate API documentation from the current diff.

## Trigger check

Before running, verify that the diff contains changes under `src/api/` or `src/routes/`. If not, ask the user to confirm before proceeding.

## Steps

1. Run `git diff --name-only HEAD` and list changed files.
2. For each changed endpoint file, extract the route, HTTP method, request schema, and response schema.
3. Update `docs/openapi.yaml` with the new or modified endpoints.
4. Report which endpoints were added, modified, or removed.

## Output format

```
Added endpoints:
  POST /api/foo
Modified endpoints:
  PUT /api/bar (request body changed)
Removed endpoints:
  (none)
```

To distribute a skill across projects:

Put the canonical SKILL.md under packages/cli/src/templates/common/skills/{name}/SKILL.md (if contributing upstream) or publish it as its own npm package.
Add a configurator step per platform that copies or adapts the skill into that platform’s layout.
Version the skill alongside the Trellis release so migrations stay consistent.

External skills: if you want to pull in a community skill, fetch the folder into the right platform directory and commit it. Trellis doesn’t currently ship an automated installer for external skills.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Custom Skills

Custom Skills

Commands vs. sub-agents vs. skills

Skill file format

Writing a skill that triggers reliably

Example: an `api-doc` skill

​Custom Skills

​Commands vs. sub-agents vs. skills

​Skill file format

​Writing a skill that triggers reliably

​Example: an api-doc skill

​Sharing skills

Custom Skills

Commands vs. sub-agents vs. skills

Skill file format

Writing a skill that triggers reliably

Example: an `api-doc` skill

Sharing skills