skill-authoring

name	skill-authoring
description	Create, validate, and maintain OpenCode skills and Codex skill wrappers (SKILL.md) for this repo.
compatibility	opencode
metadata	{"audience":"maintainers","repo":"perkcord"}

Purpose

Create durable, repo-local "skills" for OpenCode and thin Codex wrappers so repeating workflows (UI visuals, ops, releases, triage) are consistent and safe across both tools.

What a skill is

• A skill is a folder containing a SKILL.md file.
• Skills are discovered and loaded via the skill tool.
• Skills should be reusable playbooks, not one-off notes.

Where skills live

• .opencode/skills/<skill-name>/SKILL.md
• .codex/skills/<skill-name>/SKILL.md for Codex compatibility wrappers

Requirements

• File name must be exactly SKILL.md.
• Must start with YAML frontmatter.
• Frontmatter must include:
  • name
  • description
• Codex wrapper frontmatter should contain only name and description.

Naming rules

name must:

• be lowercase alphanumeric with single hyphen separators
• match the containing directory name
• be 1-64 characters

Regex: ^[a-z0-9]+(-[a-z0-9]+)*$

Content guidelines

• Prefer checklists + commands over long prose.
• Include sharp edges explicitly (credentials, webhooks, deploys, destructive commands).
• Never include secrets; document env var names and where they should be set.
• Include verification steps (how to confirm the workflow worked).

Codex compatibility wrappers

• Keep the detailed playbook in .opencode/skills/<name>/SKILL.md when OpenCode is the source of truth.
• Add or update .codex/skills/<name>/SKILL.md as a thin wrapper that points to the OpenCode source skill.
• Translate OpenCode-only tools to Codex behavior in the wrapper:
  • autocontinue_*: do not use while the repo guard is active.
  • pr_review_watch_*: use Codex GitHub tools or gh polling when unavailable.
  • Browser verification: use the Codex Browser plugin for local targets when available.
  • MCP usage: prefer active Codex MCP tools, otherwise document CLI fallbacks.
• Do not duplicate long source skill bodies into .codex/skills; this avoids drift.

Verification

After adding/editing a skill:

1. Ensure file exists at .opencode/skills/<name>/SKILL.md.
2. If Codex should trigger it, ensure .codex/skills/<name>/SKILL.md exists.
3. Ensure name matches the folder.
4. Restart OpenCode (skills are typically discovered at startup).
5. Load the OpenCode skill via the skill tool.
6. Validate Codex wrappers with Codex skill validation when available.