skillopt-skill-writer

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:

!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:

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.

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.

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:

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.