# Create A Skill

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

- Skill: `navikt/create-a-skill-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add navikt/create-a-skill-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/navikt/create-a-skill-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: navikt (https://skillmd.com/u/navikt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/navikt/create-a-skill-3

---


# Create an OpenCode-compatible Agent Skill

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.

When a skill or reference already owns the requested job, extend it within the
user's scope instead of creating a competing owner. Adapt the work to the
change; clarify only when it would materially change the requested deliverable.

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

Preserve existing invocation policy unless the task changes it. Default a new
task skill to relevance-based discovery, with a direct command when useful.
Reserve deliberate-only access for an explicit entry-point contract, not merely
because a later operation needs authorization. Reuse authorization already
granted for that action; a method or phase change does not require another ask.

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](references/principles.md). 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](references/glossary.md).

## 4. Implement and reconnect

Write the outcome, decision criteria and essential constraints. Use fixed
sequences or strict gates where order, correctness or safety requires them;
leave room for judgment elsewhere. Add only useful 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](references/opencode-validation.md). 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.

Check that the skill selects the right task and performs a useful next action
without unnecessary questions or scope expansion. A listing or forced skill
load does not prove autonomous selection. Report unexercised behavior as
unverified. In diagnose mode, a failing target is valid evidence. In
create/revise mode, iterate against observed behavior and keep the diff within
the intended contract.