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.

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