---
name: create-skill
version: 1.1.0
description: Create an agent-ops skill with one responsibility, a minimal execution contract, unambiguous English instructions, and correct routing. Use when adding a new common, project, or private SKILL.md.
---

# Create Skill

## Purpose

Create a correctly structured `SKILL.md` under `agent-ops/skills/` from the current skill template, then register its routing entry.

This skill creates skills read by the project-local `agent-ops` router. When creating a Codex-discoverable skill under `$CODEX_HOME/skills`, follow the system `skill-creator` rules instead and use only `name` and `description` in the frontmatter.

### Select the creation location

- If `.agent-ops-source` exists, create `agent-ops/skills/common/<skill-name>/SKILL.md`.
- If `.agent-ops-source` does not exist and the user explicitly requests private or operator-local visibility, create `agent-ops/skills/private/<skill-name>/SKILL.md`.
- If `.agent-ops-source` does not exist and the user does not request private visibility, create `agent-ops/skills/project/<skill-name>/SKILL.md`.

## When to use

- A repeatable task pattern is not covered by an existing skill.
- The user asks to create a specific skill.

## Inputs

- `skill-name`: Kebab-case skill name. (required)
- `purpose`: One-sentence summary of the problem the skill solves. (required)
- `visibility`: `common`, `project`, or `private`. Select `private` only when the user explicitly requests private or operator-local visibility. (optional)
- `trigger-cases`: Situations that should invoke the skill. (optional)

## Preflight

- [ ] Check `agent-ops/skills/common/`, `agent-ops/skills/project/`, and `agent-ops/skills/private/` for an existing directory with the same name.
- [ ] Check `agent-ops/skills/common/router.md` and `agent-ops/rules/project/rules.md` for equivalent routing or functionality.
- [ ] Read `agent-ops/skills/common/_templates/skill-template.md` for the current structure.

## Procedure

1. **Reject unintended duplication**
   - Stop instead of overwriting a skill in the same visibility path.
   - For a private request, treat a same-name project skill as a possible intentional override rather than an automatic duplicate. Stop and report a same-name common skill or a functional duplicate.
   - Confirm that a private override fully replaces the responsibility of its same-name project skill.

2. **Define one responsibility and its minimum contract**
   - Select only the representative trigger cases needed to distinguish this skill from existing routes. Do not pad the list to reach a target count.
   - Define the required procedure and success or failure criteria. Add inputs, preflight checks, an exact output format, or prohibitions only when they change correct execution or verdict determination.
   - Use the fewest procedure steps that preserve the workflow. Three to seven steps are a guideline for a genuinely multi-stage workflow, not a required count.
   - Include only contracts required to execute the repeated task and determine success or failure.
   - Do not add speculative inputs, states, branches, output fields, validation rules, or extension points for unsupported future cases.
   - Omit a rule that does not change an action, selection, validation result, or failure response. Link to an existing owning rule instead of restating its contract.
   - Keep exactly one independent responsibility in the skill.

3. **Write `SKILL.md`**
   - Create the file under the selected `common/`, `project/`, or `private/` path and follow `skill-template.md`.
   - Write the frontmatter `description` and Markdown instructions in English.
   - Use short imperative sentences with one meaning each. State the condition, required action, and verifiable success or failure criterion when they affect execution.
   - Do not use discretionary terms such as `appropriately`, `if needed`, or `when possible` without a decision criterion.
   - Keep the procedure specific without encoding unnecessary implementation detail.
   - Preserve paths, filenames, IDs, commands, regexes, status values, protocol tokens, and other exact literals. User-facing output literals may use the language required by the project.
   - Agent-ops internal skills may retain the local `version` convention. For Codex-installed skills, do not add nonstandard frontmatter such as `version` or `depends`.
   - Prefer reusable procedures over project-specific implementation details.
   - Remove unused optional template sections, authoring comments, and placeholders from the completed skill.

4. **Update routing**
   - If `.agent-ops-source` exists, add the routing entry to `agent-ops/skills/common/router.md`.
   - Do not add a separate route when a private skill overrides a same-name project skill; use the common private-precedence rule.
   - Route a private skill with no project counterpart only from `agent-ops/rules/private/rules.md`. If the file does not exist, create an ignored local rule containing only the private route.
   - Do not duplicate a private trigger in the project router.
   - If `.agent-ops-source` does not exist and the skill is not private, add the route to the project skill router section in `agent-ops/rules/project/rules.md`.
   - If an existing common skill only needs different triggers, update its existing row in `agent-ops/skills/common/router.md` instead of creating another skill.
   - Select the existing routing axis that matches the skill and preserve the current routing structure.

5. **Report the result**
   - Report the created file path.
   - Report the routing file and added entry.
   - Report excluded scope only when it prevents a likely misunderstanding.

## Validation

- [ ] `agent-ops/skills/{common|project|private}/<skill-name>/SKILL.md` exists.
- [ ] The skill contains the required purpose, invocation cases, procedure, and validation sections.
- [ ] Inputs, preflight, output format, and prohibitions are present only when they define a necessary contract.
- [ ] Every instruction is necessary for execution or verdict determination; no speculative contract remains.
- [ ] Instructions are concise, single-meaning, and free of discretionary wording without decision criteria.
- [ ] The frontmatter description and Markdown instructions are in English, except exact literals that must retain another language.
- [ ] No template authoring comment or unfilled placeholder remains.
- [ ] The frontmatter has a valid `name` and `description`.
- [ ] An agent-ops skill follows local frontmatter conventions, while a Codex-installed skill follows the system `skill-creator` frontmatter rules.
- [ ] A private override takes precedence over its same-name project skill, and only an unmatched private skill is routed from the private rule.
- If validation fails, report the missing or conflicting item and change only that item.

## Output format

```markdown
## 생성 완료

- SKILL 경로: agent-ops/skills/{common|project|private}/<skill-name>/SKILL.md
- 라우팅 추가: <대상 파일> → <라우팅 축> → <skill-name>

## 주의사항 (해당 시)

- <이 skill이 다루지 않는 범위 또는 주의할 점>
```

## Prohibitions

- Do not copy private skill or private rule content into tracked common or project paths.
- Do not overwrite an existing skill.
- Do not hardcode project-specific paths such as `app/screens/` in a reusable skill.
- Do not modify code unrelated to skill creation.
- Do not delete or reorder existing routing entries.
- Do not combine multiple independent responsibilities in one skill.
- Do not add contracts for hypothetical future requirements.
- Do not use ambiguous instructions without executable decision criteria.