---
name: creating-skills
description: Create or update opencode skills in this repository using the required SKILL.md format and concise, trigger-focused guidance
permalink: opencode-config/skills/creating-skills/skill
---

# Creating Skills

Use this skill when you need to add or revise an opencode skill under `skills/`.

## Skills vs OpenAI/Codex Source Model

- Treat this repo as **opencode-native**.
- Do **not** use OpenAI/Codex-specific artifacts such as `agents/openai.yaml`, `init_skill.py`, `quick_validate.py`, or `scripts/references/assets` conventions from the old source model.
- A skill is discovered from `skills/*/SKILL.md` only.

## Required Structure

1. Create a folder at `skills/<skill-name>/`.
2. Add `skills/<skill-name>/SKILL.md`.
3. Keep `<skill-name>` equal to frontmatter `name`.

Frontmatter must contain only:

```yaml
---
name: <skill-name>
description: <what it does and when to load>
permalink: opencode-config/skills/<skill-name>/skill
---
```

## Naming Rules

- Use lowercase kebab-case.
- Keep names short and action-oriented.
- Match folder name and `name` exactly.

## Body Writing Rules

- Write concise, imperative instructions.
- Lead with when to load and the core workflow.
- Prefer short checklists over long prose.
- Include only repo-relevant guidance.
- Keep the planner/builder operating model in mind when a skill touches workflow behavior.

## Companion Notes (`*.md` in skill folder)

Add companion markdown files only when detail would bloat `SKILL.md` (examples, deep procedures, edge-case references).

- Keep `SKILL.md` as the operational entrypoint.
- Link companion files directly from `SKILL.md` with clear “when to read” guidance.
- Do not create extra docs by default.

## Practical Workflow (Create or Update)

1. Inspect 2–3 nearby skills for local style and brevity.
2. Pick/update `<skill-name>` and folder path under `skills/`.
3. Write or revise `SKILL.md` frontmatter (`name`, `description`, `permalink` only).
4. Draft concise body sections: purpose, load conditions, workflow, red flags/checks.
5. Add minimal companion `.md` files only if needed; link them from `SKILL.md`.
6. Verify discovery path and naming consistency:
   - file exists at `skills/<name>/SKILL.md`
   - folder name == frontmatter `name`
   - no OpenAI/Codex-only artifacts introduced
7. If the skill changes agent workflow or command behavior:
   - Update the **Skills** table, **Agent Skill-Loading Contract**, and **TDD Default Policy** in `AGENTS.md`.
   - Confirm `commands/*.md` and any affected `agents/*.md` prompts stay aligned.
   - If the skill involves parallelization, verify it enforces safe-parallelization rules (no parallel mutation on shared files, APIs, schemas, or verification steps).
    - If the skill involves code changes, verify it references the TDD default policy and its narrow exceptions.

## Language/Ecosystem Skill Pattern

When adding a new language or ecosystem skill (e.g., `rust-development`, `go-development`), follow this template:

1. **Name**: `<language>-development` (kebab-case).
2. **Load trigger**: presence of the language's project file(s) or source files as primary source.
3. **Defaults table**: one row per concern — package manager, linter/formatter, test runner, type checker (if applicable).
4. **Core workflow**: numbered steps for bootstrap, lint, format, test, add-deps, and any lock/check step.
5. **Conventions**: 3–5 bullets on config file preferences, execution patterns, and version pinning.
6. **Docker integration**: one paragraph on base image and cache strategy.
7. **Red flags**: 3–5 bullets on common anti-patterns.
8. **AGENTS.md updates**: add the skill to the **Ecosystem Skills** table and add load triggers for `planner`, `builder`, `coder`, and `tester` in the **Agent Skill-Loading Contract**.
9. **Agent prompt updates**: add the skill trigger to `agents/planner.md`, `agents/builder.md`, `agents/coder.md`, and `agents/tester.md`.