---
name: waylish/skillopt-skill-writer
source: https://app.decimal.ai/s/waylish-skillopt-skill-writer@1/SKILL.md
source_sha256: 229f4c8eef6e
---

# SkillOpt Skill Writer / SkillOpt 技能写作器

Use this skill to write or improve agent skills as compact, testable procedural artifacts. The method is inspired by SkillOpt: treat one `SKILL.md` as the trainable state, make bounded edits, accept changes only after validation, and keep rejected edits as negative feedback.

中文使用原则：当用户用中文描述需求时，用中文产出 brief、验证说明和最终回复；`SKILL.md` 的技术标识、文件名、命令、frontmatter 字段保持英文或 ASCII。触发词、README、模板和说明应尽量中英文双语，方便中文用户使用，也方便 GitHub 搜索。

## Step 1: Detect Runtime and Inputs

Run only the checks that are relevant to the current environment. If a command is unavailable, use the fallback path and record the gap.

Detection commands:

```bash
!pwd || cd
!rg --version || grep --version || echo "no-fast-search"
!git --version || echo "no-git"
!rg --files -g SKILL.md . || find . -maxdepth 4 -name SKILL.md || dir /s /b SKILL.md
!test -f SKILL.md && echo "current-skill" || echo "no-current-skill"
```

Decision tree:

| Detected state | Path |
|---|---|
| User provided a workflow but no existing skill | Create a new skill from a seed draft |
| User provided an existing `SKILL.md` | Improve it with bounded edits |
| User provided tasks, expected outputs, tests, or scorer | Use scored validation gate |
| No scorer or test tasks are available | Use static rubric + 2-3 dry-run prompts and mark as `dry_run` |
| Git is available and workspace is a repo | Keep before/after diff and avoid unrelated changes |
| Git is unavailable | Keep an edit log in `rejected_edits.md` / `validation_notes.md` |

Exit gate: identify mode (`create`, `improve`, or `evaluate`), available validation path, target runtime, and output location.

## Step 2: Build the Skill Brief

Extract the minimum brief before drafting. Do not stall if fields are missing; use the defaults table.

| Parameter | Default | Rationale |
|---|---|---|
| Target runtime | Codex-compatible `SKILL.md` | Current environment uses Codex skills |
| User level | Competent practitioner | Avoid both toy explanations and unexplained jargon |
| Skill mode | Create if no `SKILL.md`, improve if one exists | Matches user intent from artifacts |
| Output artifact | `SKILL.md` plus references when useful | Standard skill packaging |
| Main language | User's language, with technical identifiers unchanged | Preserves usability and triggers |
| Reference files | 1-3 files for rubrics/templates/deep method | Keeps main skill compact |
| Validation | Automatic scorer if available, otherwise rubric + dry run | Always produces a result |
| Edit budget | Max 4 atomic edits per improvement round | Textual learning-rate analogue |
| Acceptance rule | Strict improvement over current validation score | Prevents silent drift |
| Rejected memory | Keep concise rejected-edit notes | Supplies negative feedback |

Deliverable: a one-paragraph skill brief naming task, trigger scope, inputs, outputs, tools, constraints, and validation route.

## Step 3: Create the Seed Skill

Write the first `SKILL.md` as a procedural artifact, not an essay.

Required structure:

1. YAML frontmatter with `name` and a trigger-rich `description`.
2. One-sentence purpose statement.
3. `## Step 1: Detect...` runtime/input detection flow.
4. 5-9 numbered workflow steps with explicit deliverables.
5. Defaults table covering every parameter that could otherwise cause a question.
6. Failure handling and fallback paths.
7. Final response template with numbered output sections.
8. `## Reference Files` section when details are deferred.

Pass gate:

- Frontmatter parses as YAML.
- Description contains 10+ trigger phrases including beginner and sideways phrasing.
- Main file is under 300 lines unless the domain genuinely requires more.
- Every step has an exit gate or concrete deliverable.

## Step 4: Design Validation Before Editing

Validation must exist before optimizing the skill.

| Available evidence | Validation method |
|---|---|
| Unit tests, benchmark tasks, exact answers, executable checks | Run them and compute score |
| Example prompts with expected output traits | Score with a rubric and record pass/fail |
| No examples | Generate 2-3 representative dry-run prompts from the brief |
| Existing production failures | Convert failures into test prompts before editing |

Minimum validation set:

- 1 common happy-path prompt.
- 1 ambiguous or underspecified prompt.
- 1 failure-prone prompt tied to the domain.

Exit gate: write `validation_plan.md` or an equivalent section containing prompts, expected behavior, scoring criteria, and baseline notes.

## Step 5: Optimize with Bounded Edits

Use SkillOpt-style edit discipline. Each optimization round must operate on one current skill.

1. Collect evidence from validation results or dry-run analysis.
2. Split evidence into failures to correct and successes to preserve.
3. Propose atomic edits only:
   - `ADD`: insert a missing rule, fallback, trigger, default, or output requirement.
   - `DELETE`: remove a harmful, vague, stale, or redundant instruction.
   - `REPLACE`: rewrite one bounded section for specificity or correctness.
4. Rank edits by expected impact.
5. Apply at most the edit budget, default 4 edits.
6. Re-run validation.

Acceptance gate:

- Accept the candidate only if the validation score strictly improves.
- If scores tie, keep the previous skill unless the user explicitly accepts the neutral change.
- If validation worsens, reject the candidate and log the attempted edits with the failure reason.

## Step 6: Maintain Rejected-Edit Memory

Create or update a short rejected-edit buffer during the same work session.

For each rejected edit, record:

| Field | Meaning |
|---|---|
| Edit ID | Stable label such as `R001` |
| Edit type | `ADD`, `DELETE`, or `REPLACE` |
| Intended fix | What failure it tried to solve |
| Rejection reason | Lower score, vague output, runtime drift, broken trigger, user mismatch |
| Future warning | What not to repeat |

Use the buffer as negative feedback in later rounds. Do not ship rejected-edit memory inside the deployed `SKILL.md` unless the user asks for an audit trail.

## Step 7: Add Slow/Meta Lessons

After one or more edit rounds, write a short meta note outside the deployed skill:

- Durable failure patterns.
- Rules that improved validation.
- Rules that looked plausible but failed.
- Runtime constraints to preserve.
- Open validation gaps.

If a durable lesson belongs in the deployed skill, add it through the same bounded-edit and validation gate. Never let a meta note silently overwrite the skill.

Exit gate: deployed `SKILL.md` remains compact, while `validation_notes.md` captures longer-horizon lessons.

## Step 8: Respond to the User

Use this final response template:

1. **Existence Check**: Mention whether an existing matching skill was found and how close it is.
2. **Artifact**: Link the generated or improved `SKILL.md` and reference files.
3. **Validation**: State whether validation was scored, dry-run, or not possible.
4. **Accepted Changes**: Summarize accepted bounded edits.
5. **Rejected / Risks**: Mention rejected edits or remaining validation gaps.
6. **Use**: Explain where to place the skill if the user wants to install it.

Keep the response short. Do not paste the full skill unless the user asks.

## Reference Files

- `references/skillopt-method.md`: SkillOpt concepts translated into skill-writing rules.
- `references/validation-gates.md`: scoring, dry-run validation, and acceptance gates.
- `references/templates.md`: seed skill, edit log, and final response templates.