116 lines
7.5 KiB
Markdown
116 lines
7.5 KiB
Markdown
---
|
|
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.
|