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:

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.