dotfiles/.config/opencode/skills/creating-skills/SKILL.md

name, description, permalink

name	description	permalink
creating-skills	Create or update opencode skills in this repository using the required SKILL.md format and concise, trigger-focused guidance	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:

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