create-skill · diff
git:20260628.325c1b7 to git:20260831.b100768
31 added, 19 removed. Audit A to A.
---
name: create-skill
plugin: agent-scaffolders
description: >
Creates a new stateless skill in an existing plugin. Use this for procedural skills with no persistent state. NOT for sub-agents (use `create-sub-agent`) and NOT for skills that need stateful counters or session memory (use `create-stateful-skill`).
argument-hint: "[skill-name or use-case description]"
allowed-tools: Bash, Read, Write
---
<example>
<commentary>User wants to create a brand-new skill from scratch.</commentary>
user: "Create a new skill called link-validator"
assistant: [triggers create-skill, runs discovery interview, scaffolds directory structure with SKILL.md, evals/evals.json, references/acceptance-criteria.md]
</example>
<example>
<commentary>Negative — user wants to improve an existing skill, not scaffold a new one.</commentary>
user: "Improve the trigger description for my link-checker skill"
assistant: [triggers os-improvement-loop, not create-skill]
</example>
# create-skill: Skill Scaffolding Executor
Scaffolds a complete, standards-compliant agent skill directory. Handles filesystem
operations, template rendering, name validation, and discovery — then hands off to
the TDD quality gate.
**Scope**: This skill owns *structure*. It does not own *content quality* or *routing accuracy*.
Those are governed by `os-improvement-loop` (see cross-plugin handoff below).
---
## Inputs
- `$ARGUMENTS` — optional skill name or brief use-case description passed as initial
context to the discovery phase. Omit to start with open discovery.
---
## Phase 1: Discovery Interview
Before writing any files, capture all required inputs:
1. **Skill name** — lowercase-hyphen slug (e.g. `link-validator`). Validate: no spaces,
no special characters, no shell injection sequences (reject names containing `;`, `&`, `|`, `$`, `` ` ``).
2. **Purpose** — one sentence: what does this skill do and when does it fire?
3. **Target plugin** — which plugin directory will own this skill?
4. **Trigger phrases** — 3-5 specific phrases a user would say to invoke it.
5. **Tools needed** — which `allowed-tools` does it require?
If `$ARGUMENTS` is provided, treat it as a starting point and confirm rather than re-ask.
---
## Phase 2: Plan and Confirm
Present the proposed directory layout before writing anything:
```
plugins/<plugin>/skills/<skill-name>/
SKILL.md
evals/
evals.json
references/
acceptance-criteria.md
./scripts/ (if the skill needs Python helpers)
./assets/ (if the skill needs static resources)
```
**Confirm with the user before proceeding.** If a directory with that name already exists:
> "Warning: `<path>` already exists. Overwrite? (yes/no)"
> Do NOT overwrite without explicit confirmation.
---
## Phase 3: Scaffold
Create the confirmed directory structure. Standards enforced by `acceptance-criteria.md`:
- - **Python only** — helper scripts go in `scripts/*.py`. Never generate `.sh` bash scripts.
- - **Symlink, don't copy** — if the skill needs a Python helper that lives at the plugin root's
- `scripts/` directory, create a **file-level symlink** in `skills/<skill>/scripts/` pointing to
- `../../../scripts/<canonical_name>.py`. Never duplicate the file. The symlink filename may differ
- from the target (e.g. `execute.py` → `exploration_optimizer_execute.py`). Create with:
+ - **Python only** — helper scripts go in plugin root `scripts/*.py`. Never generate `.sh` bash scripts.
+ - **Symlink, don't copy (ADR-002/003)** — if the skill needs a Python helper that lives at the plugin root's
+ `scripts/` directory, create a **file-level symlink** using `symlink_manager.py`:
```bash
- ln -s ../../../scripts/<canonical_name>.py skills/<skill>/scripts/<name>.py
+ python3 .agents/skills/symlink-manager/scripts/symlink_manager.py create \
+ --src plugins/<plugin>/scripts/<canonical_name>.py \
+ --dst plugins/<plugin>/skills/<skill>/scripts/<name>.py
```
- Verify the symlink resolved: `python -c "import os; print(os.path.exists('skills/<skill>/scripts/<name>.py'))"`
- must print `True`. On Windows/`core.symlinks=false` machines, git will check these out as
- plain-text "stand-in" files — run `bulk_symlink_fixer.py` to restore them after checkout.
- - **Starter SKILL.md** — frontmatter with `name`, `description` (use the purpose from Phase 1; **MUST NOT exceed 1024 characters**),
- `allowed-tools`. Body: stub sections for Identity, Steps, and Common Failures.
- - **Starter evals.json** — at least 2 placeholder eval cases using the `should_trigger` schema:
+ Never use raw `ln -s` directly.
+ - **Starter SKILL.md (Layer 1 Core)** — target **<= 100 lines**. Frontmatter with `name` (matches directory),
+ `description` (third-person active verb, **MUST NOT exceed 1024 characters**), `allowed-tools`.
+ Keep the body focused strictly on procedural steps; offload operational background, schemas, and tables to `references/<topic>.md` (Progressive Disclosure).
+ - **Starter evals.json** — root JSON array of at least 2 placeholder eval cases using the `should_trigger` schema:
```json
- { "id": "eval-1-positive", "type": "positive", "prompt": "REPLACE", "should_trigger": true }
- { "id": "eval-2-negative", "type": "negative", "prompt": "REPLACE", "should_trigger": false }
+ [
+ { "id": "eval-1-positive", "type": "positive", "prompt": "REPLACE", "should_trigger": true },
+ { "id": "eval-2-negative", "type": "negative", "prompt": "REPLACE", "should_trigger": false }
+ ]
```
- > ⚠️ **Schema requirement**: Always use `should_trigger: true/false`. The legacy
- > `expected_behavior` string field is ignored by the eval scorer and will produce 0% accuracy.
- - **acceptance-criteria.md** — write to `references/acceptance-criteria.md` with the
- acceptance criteria captured in Phase 1.
+ > ⚠️ **Schema requirement**: Always use root JSON array with `should_trigger: true/false`. The legacy
+ > `expected_behavior` string field and dictionary wrappers are deprecated.
+ - **acceptance-criteria.md & fallback-tree.md** — wire standard contract symlinks from plugin `references/` via `symlink_manager.py`.
---
- ## Phase 4: Quality Gate Handoff
+ ## Phase 4: Quality Gate & Alignment Verification
+ Run `audit_skill.py` to verify the scaffolded skill satisfies all 6 evolution invariants:
+
+ ```bash
+ python3 plugins/agent-scaffolders/scripts/audit_skill.py plugins/<plugin>/skills/<skill-name>
+ ```
+
+ Ensure the output displays `[✅ PASS]` with 0 errors before proceeding to `os-improvement-loop` for routing calibration.
+
+ ---
+
## Dependencies
+ - **symlink-manager** (dev-utils plugin)
+ - **audit-skill** (agent-scaffolders plugin)
- **os-improvement-loop** (agent-agentic-os plugin)
> [!TIP]
> See [INSTALL.md](https://github.com/richfrem/agent-plugins-skills/blob/main/INSTALL.md) for instructions on how to install missing dependencies.
**If `os-improvement-loop` is available**, hand off immediately after scaffolding:
```
Invoke os-improvement-loop on the newly scaffolded skill at <path>.
The RED scenario is: [trigger phrase from Phase 1 discovery].
Run the RED-GREEN-REFACTOR cycle to verify routing accuracy before shipping.
```
**If not available**, advise the user:
```
Scaffold complete. To verify routing accuracy and trigger description quality, ensure **os-improvement-loop** is installed. See [INSTALL.md](https://github.com/richfrem/agent-plugins-skills/blob/main/INSTALL.md).
```
---
## Phase 5: Report
```
✅ Scaffolded: plugins/<plugin>/skills/<skill-name>/
Files created: SKILL.md, evals/evals.json, references/acceptance-criteria.md
Quality gate: [PASSED via os-improvement-loop | SKIPPED — os-eval-runner not installed]
Next: fill in REPLACE placeholders in evals/evals.json, then run os-eval-runner baseline
```
---
## Edge Cases
- **Empty `$ARGUMENTS`**: begin with Phase 1 discovery — do not skip to scaffolding
- **Existing directory**: dual-confirmation before any overwrite (see Phase 2)
- **Improving an existing skill**: redirect to `os-improvement-loop` capability — that skill owns content
quality and routing improvement. `create-skill` is for net-new scaffolding only.
- **Scaffold script crash**: read the Python stack trace, correct obvious errors, or surface
the full trace to the user — do not silently skip
- **Template rendering failure**: do not output partially-rendered content; provide the
base template inline and instruct the user to fill values manually
---
## References
- [`acceptance-criteria.md`](references/acceptance-criteria.md) — structural pass/fail criteria
- [`fallback-tree.md`](fallback-tree.md) — error handling procedures
- **Architectural Decision Records (ADRs)** located at `references/ADRs/`. Always consult them for standards on plugin architecture, shared scripts, cross-plugin dependencies, symlinking, and loose coupling to avoid repeating yourself.
- **`os-improvement-loop`**: TDD methodology, RED scenario protocol, eval gate.
- **`os-eval-runner`**: autoresearch eval loop for skill optimization.