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.

1. Rank edits by expected impact.
2. Apply at most the edit budget, default 4 edits.
3. 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.