Creating Custom Skills

Skills are the backbone of Systematic. They are structured Markdown files that guide the AI through specific engineering processes. While Systematic comes with several bundled skills, you can easily create your own to capture your team’s unique workflows.

What is a Skill?

A skill is a Markdown file with a specific YAML frontmatter. When a skill is loaded into a conversation, its content is injected into the AI’s context, providing it with detailed instructions on how to perform a specific task.

The SKILL.md Format

Custom skills should be placed in .opencode/skills/<skill-name>/SKILL.md. The file must start with a YAML frontmatter block.

---
name: my-custom-workflow
description: This skill should be used when [trigger condition]. It [what it does].
---

# My Custom Workflow

Detailed instructions for the AI go here. You can include:
- Checklists
- Examples of good/bad output
- Tool usage guidelines
- Reference to other skills

Frontmatter Fields

• name: A unique, slug-ified name for your skill (e.g., feature-release-checklist).
• description: CRITICAL. This field is used by OpenCode to match the user’s request to the skill. It should clearly state when the skill should be triggered and what it achieves.

Triggering Skills

OpenCode automatically invokes skills based on their description. To ensure your skill is triggered reliably, include specific trigger phrases in the description:

“Triggers on ‘let’s release’, ‘deploy to production’, ‘create a patch’, or when the user asks about the release process.”

Best Practices for Writing Skills

1. Focus on “How”, Not “What”

Don’t just tell the AI to “do a code review.” Tell it exactly which files to read, what patterns to look for, and how to format its findings.

2. Use Checklists

AI agents are excellent at following structured checklists. Use them to ensure no steps are skipped in complex workflows.

3. Incorporate Tool Mapping

If your skill references specific tools, include a tool mapping section to ensure compatibility across different OpenCode environments:

**Tool Mapping for OpenCode:**
- `TodoWrite` → `todowrite`
- `Task` → `@mention` or `task`
- `Read` → `read`

4. Keep it Human-Readable

While the content is for the AI, it should be readable and maintainable by humans. Use clear headings and well-formatted Markdown.

Testing Your Skill

Once you’ve created your SKILL.md file, you can test it in an OpenCode conversation:

1. Restart OpenCode (or the plugin) to pick up the new file.
2. Type a message that matches your skill’s trigger description.
3. Verify that the AI announces it is using your skill and follows its instructions.