--- name: create-skill description: Author a new omp-native skill. Use when the user wants to capture a recurring workflow, create a skill from scratch, formalize a procedure into a SKILL.md, scaffold a new skill under ~/.omp/agent/skills/, or "turn this into a skill". tags: [authoring, meta, omp-native] --- # Create Skill You are helping the user author a new **omp-native skill** — a `SKILL.md` file that lives under `~/.omp/agent/skills//` (user scope) or `/.omp/skills//` (project scope) and gets discovered by `omp` at session start. This skill is intentionally minimal. It walks you through the author loop using only `omp`'s standard tools (`read`, `write`, `edit`, `bash`). It does NOT shell out to other coding agents and does NOT depend on any external CLI. ## What a skill is, in two sentences A skill is a markdown file. Only its frontmatter `description` reaches the system prompt at session start (that's the *trigger*); the body is injected as a user message when the user runs `/skill:` or when the model decides the description matches. Co-located files (scripts, references, assets) ship next to it on disk and are reachable on demand via `read` / `bash`, but they are **never** auto-loaded into the context. So a well-authored skill is two things at once: 1. A **trigger** (frontmatter `description`) that fires when it should and stays silent otherwise. 2. A **playbook** (SKILL.md body) the agent follows once triggered, naming any co-located files it should reach for. Both matter. A vague trigger never fires; a specific trigger that points to empty guidance wastes a turn. Tune both. ## The loop Work through these in order. Skip steps the user has already given you answers to; never invent details to fill silence. ### 1. Capture intent Ask the user: - **What should this skill enable the agent to do?** One sentence. If they answer "a lot of things", narrow until you can name a single shape (e.g. "scaffold a Vite + Tailwind project" not "do frontend work"). - **When should it trigger?** What phrase, request, or symptom should make `omp` reach for this skill? Two or three concrete examples. - **Scope.** User-level (`~/.omp/agent/skills/`) or project-level (`/.omp/skills/`)? Default to user unless the skill is project-specific (touches `.claude/`-style config, depends on a particular file layout, etc.). - **Co-located files.** Will the skill ship scripts (`scripts/foo.py`), reference docs (`references/`), starter assets (`assets/`)? Capture the list now even if you write the files later. If the user is updating an existing skill rather than creating one, jump straight to step 4 (revise) after locating the existing `SKILL.md`. ### 2. Choose the name and pick the path The **directory name** under `skills/` is what `/skill:` resolves to. Keep it short, lowercase, kebab-case. Match the frontmatter `name` field to the directory name unless you have a reason not to. The full target path is: ``` ~/.omp/agent/skills//SKILL.md # user scope /.omp/skills//SKILL.md # project scope ``` Before writing, verify the directory doesn't already exist. If it does, ask the user whether to overwrite, pick a new name, or revise the existing skill. ### 3. Write the description This is the load-bearing step. The frontmatter `description` is the *only* signal `omp` gives the model about your skill at session start. Get it wrong and the skill silently never fires. Rules: - Lead with **what the skill does**, not who wrote it or how cool it is. - Use the form `Use when — `. Examples that work: - `Use when a PowerShell 5.1 wrapper around a native exe falsely reports failure because it captured benign stderr INFO logs as ErrorRecords.` - `Use when round-tripping a UTF-8 file via PS 5.1 Get-Content + Set-Content -Encoding utf8 corrupts em-dashes to "â€"" and similar mojibake.` - Name the symptom in concrete terms ("crashes after 2-3 deploys", "fails with HTTP 401", "produces empty output"). Vague is dead. - Keep it to **one or two sentences**. Long descriptions get truncated. - If the skill is procedural ("when X happens, do Y"), make sure the trigger half names X, not Y. The model decides whether to fire based on whether X matches its current task. If you can't write a tight description, the skill might not be well-defined yet. Back up to step 1. ### 4. Draft the SKILL.md Layout: ```markdown --- name: description: tags: [] --- # ##
##
1. Step one — name the exact tool to use. 2. Step two — point at any co-located files by relative path (`scripts/foo.py`, `references/schemas.md`). 3. ... ## Notes / failure modes ``` Concrete > abstract. The agent benefits more from "run `bash` with `npm run build && npm test`" than from "ensure quality." Always. Reference co-located files by relative path; the agent will resolve them against the skill's `baseDir`. ### 5. Write it to disk Use `omp`'s `write` tool to create both the directory (`write` creates parents) and the file. Example: ``` write ~/.omp/agent/skills//SKILL.md ``` If you're also shipping scripts or references, write them now too. Keep the tree tidy: ``` / ├── SKILL.md # required ├── scripts/.py # optional ├── references/.md # optional └── assets/ # optional ``` ### 6. Verify Three checks, in this order: 1. **File is on disk.** `bash ls -la ~/.omp/agent/skills//` (or `dir` on Windows). Confirm SKILL.md is present and non-empty. 2. **omp can see it.** If the user is running omp-deck, hit `GET http://127.0.0.1:8787/api/skills` and confirm the new skill appears with `provider: "native"`. If the user is on bare omp, ask them to run `omp` once and check the system prompt loaded it. 3. **The trigger fires when it should.** Suggest the user open a fresh session and describe the situation the skill is for. Watch whether the agent reaches for the skill (look for `/skill:` in the trace, or just the agent saying "I'll use the skill"). If it doesn't fire, tune the description. ### 7. Iterate Skills get better by use. If the description doesn't trigger when it should, tighten the symptom language; if it triggers when it shouldn't, narrow the situation. Edit `SKILL.md` directly with the `edit` tool; `omp` re-reads on the next session start. ## What to avoid - **`claude -p` references.** This skill is omp-native. If the user's workflow really does require shelling out to Claude Code, capture it as a project skill in `/.omp/skills/`, not as a portable user skill — and document the dependency in the SKILL.md body. - **Task-tool subagent names.** `omp` has subagents (`omp agents`) but the wire format is different from Claude Code's Task tool. If the skill needs subagents, talk to the user about whether they want a subagent (separate authoring step) or just guidance the main agent follows. - **Pre-rendering co-located files into SKILL.md.** That defeats progressive disclosure. Keep scripts as scripts; reference them by path. - **Trigger phrases inside the SKILL.md body.** Trigger lives in frontmatter `description`. The body is the playbook the model follows *after* triggering. ## When the user just wants to update an existing skill Quick path: 1. Read the current `SKILL.md` with the `read` tool. 2. Discuss the change with the user — is it the trigger (description), the playbook (body), or both? 3. Use `edit` for surgical changes; `write` only if you're rewriting the whole file. 4. Re-run step 6 (verify). ## When the user wants project scope The active session's `cwd` matters. Write to `/.omp/skills//SKILL.md` instead of the user-level path. The deck's `/skills` view will show the new skill with `level: "project"` when it's opened against that cwd. --- When you're done, summarize for the user: - Skill name + path - The exact trigger sentence - How to invoke it (`/skill:`) - Any co-located files you shipped, and what they're for