| name | grillmester-create-a-skill |
| description | Create, revise, review, or diagnose a portable Agent Skill for OpenCode v1, including native discovery, permissions, and an optional slash-command adapter. Use when a user asks to create or improve a skill, investigate why one does not load, or validate skill behavior. |
Create an OpenCode-compatible Agent Skill
OpenCode v1: Backticked grillmester-* names below are skill IDs, not slash commands. Load them with the native skill tool. Slash commands are direct user entry points only.
Create, revise, or diagnose one portable Agent Skill. Repository instructions,
the installed OpenCode v1 contract, and the target repository's chosen skill
root govern the artifact.
Choose the mode
- Create or revise — inspect, design, edit, reconnect callers, and validate.
- Diagnose or review — inspect and validate read-only, then report evidence
and recommendations. Edit only if the user also requested implementation.
Stop and recommend extending an existing owner when the requested behavior is
already owned by a skill or reference.
1. Inspect the target
Inspect applicable AGENTS.md, OpenCode config, existing skills, neighboring
commands, and repository validation. Determine which supported root the
repository already uses:
.agents/skills/<name>/SKILL.md for a portable project skill;.opencode/skills/<name>/SKILL.md for an OpenCode-specific project skill;- the corresponding supported user-level root only when the user requested a
personal skill.
Do not introduce a parallel skill tree without a material reason and user
agreement. State the skill's one job, its boundary, current callers, and
whether it needs a separate slash command.
2. Design discovery and invocation
Use portable skill frontmatter:
name — required, kebab-case, and equal to the directory name;description — required, concise, and specific enough for model discovery;license, compatibility, and metadata — optional only when they convey a
real portable contract.
Do not copy client-specific invocation keys into an OpenCode skill. OpenCode
loads skills through the skill tool. Control model access with ordered
permission.skill patterns in agent or project configuration. When a direct
slash entry point matters, add a native command with the same stable ID under
the selected OpenCode commands/ root; the wrapper must load the skill and
pass $ARGUMENTS as user input.
For access rules, put "*" before narrower patterns because the last matching
rule wins. Use ask for a source skill that was intended to require deliberate
human invocation; this is an approval approximation, not provenance-aware
manual-only behavior.
3. Design the information hierarchy
Apply the authoring principles. Keep instructions
needed every time in SKILL.md; put conditional reference, scripts, and assets
beside it and link them with an explicit loading condition. Consult only the
needed heading in the glossary.
4. Implement and reconnect
Write the smallest complete skill and only justified bundled resources. Update
direct callers, command wrappers, adapter policy, and provenance affected by a
name or invocation change. If a repository generates its OpenCode target,
change the canonical source or target overlay and regenerate; never hand-edit
the generated output.
Complete the edit when names are stable, links resolve, target roots do not
compete, permissions preserve the intended boundary, and the diff contains no
unrelated client assumptions.
5. Validate and forward-test
Immediately before validation, read
the OpenCode validation checklist. Run its
safe structural and runtime checks using a disposable target/config copy when
the client may create dependency artifacts. Test explicit command invocation,
positive skill discovery, a close negative prompt, and every distinct branch
that can be exercised without unauthorized external writes.
In diagnose mode, a failing target is valid evidence. In create/revise mode,
iterate until structure, discovery, permission behavior, and the final diff
match the intended contract.
