laohan-skillcreator

laohan Skill Creator · Auditor · Fixer · Optimizer

Creation is a production capability, auditing is read-only diagnosis, fixing is small-scope error correction, and optimization is experimental evolution. Determine the mode first, then use verification proportional to the risk; a single clear small fix must not be escalated into a full optimization project.

Reference sources

Currently draws on 6 groups of upstream sources. The specific files and most recent verified commits are recorded in references/upstream-sources.json. When modifying this Skill itself or when the user asks to update the methods, first run scripts/check-upstreams.sh; after discovering upstream changes, read the relevant diff and absorb only the changes that can improve real local behavior, without automatically overwriting local methods.

anthropics/skills · skill-creator（https://github.com/anthropics/skills）
- Drawn from: progressive disclosure (metadata→body→bundled three layers), same-condition baseline comparison, blind comparison, description optimizer, finding repetitive work from transcripts, keeping the original name when updating
- Core idea: a good skill has three layers of progressive disclosure, not one big blob
Agent Skills specification / best practices（https://github.com/agentskills/agentskills）
- Drawn from: frontmatter common conventions, progressive disclosure, real experience first, matching control strength to task fragility, removing ineffective steps from execution traces
- Core idea: a Skill should supplement the domain experience the agent lacks, not repeat common sense; being overly comprehensive likewise degrades effectiveness
mattpocock/skills · writing-great-skills（https://github.com/mattpocock/skills）
- Drawn from: trigger branches, information hierarchy, completion conditions, single source of truth, removing duplication/sediment/no-op
- Core idea: a Skill pursues predictable process, not identical output for everything; different branches only load the information each needs

thananon/9arm-skills · debug-mantra/post-mortem/scrutinize（https://github.com/thananon/9arm-skills）
- Drawn from: verbatim recitation (first time once + verbatim + silent apply), hard-gating wording, refuse to draft, cross-skill offer not automatic, question intent first, cite or it didn't happen
- Core idea: when uncertain, stop; every claim must have a citation
alchaincyf/darwin-skill + SkillLens / SkillOpt（https://github.com/alchaincyf/darwin-skill）
- Drawn from: 9-dimension scoring system, 8-item counterexample blacklist, ratchet mechanism (git ratchet), independent subagent re-review, 5-stage human-in-the-loop
- Core idea: SkillLens shows that LLM pairwise judgments without a rubric are only 46.4% accurate, and a verified meta-skill rubric raises that to 73.8%, still not enough to replace real task verification
obra/superpowers · writing-skills（https://github.com/obra/superpowers）
- Drawn from: only deep creation/optimization does no-Skill baseline and stress scenarios; mechanically executable constraints are preferably delegated to scripts or verifiers
- Core idea: testing should prove that the Skill changed actual behavior, but TDD ritual must not be imposed on a clear small fix

Core idea

Four principles:

Routing determines cost — name + description are responsible for letting the agent find the Skill, and the first step of the body is responsible for choosing the correct branch; accurate triggering does not mean the heavy process is run every time
Structure guides behavior — a good skeleton is more effective than good instructions
Concise beats complete — every section must prove its value in existing
Effect comes before format score — a static rubric is used to find problems; triggering, execution, held-out samples, and user acceptance determine whether a change is kept

Choose the mode first

Choose only one primary mode each time:

Mode	When to use	Default verification strength
`CREATE`	Create a reusable Skill	Real samples, trigger/counter-trigger, execution tests; for complex or high-impact Skills, add held-out
`AUDIT`	Health check, scoring, reasonableness check	Read-only, cite specific lines and behavioral evidence; do not modify files
`SURGICAL_FIX`	Restore the original version, fix clear errors, update fixed contracts or paths	Compare against the source of truth, make minimal changes, directly cover that error with targeted regression; do not do static scoring, blind judge, or unrelated held-out
`OPTIMIZE`	The user explicitly requests improving effectiveness, comparing old and new approaches, or comprehensive evolution	Freeze baseline/metrics, run held-out; use blind judge only for subjective results
`UPSTREAM_REFRESH`	Update the methods this Skill draws on or verify whether references have changed	Run upstream checks, read the changes, merge only relevant gains, and update the recorded commit

The user says "modify the Skill" but provides a clear error or the original source of truth, default to SURGICAL_FIX; only enter OPTIMIZE。AUDIT does not imply authorization to fix,CREATE does not imply authorization to install or publish.

Upstream update

UPSTREAM_REFRESH and modifying laohan-skillcreator itself:

Run bash scripts/check-upstreams.sh。
CURRENT: continue the current task.
UPDATED: read the diff of relevant files from the recorded commit to the latest commit, and determine whether it changes the locally drawn-on methods.
Modify this Skill only if there is a genuine gain; if there is no relevant gain, only update the verification notes, and do not copy the upstream full text.
After verifying that the local mode routing has not regressed, update references/upstream-sources.json 's commit and verified_at。
UNVERIFIED: report that verification is impossible, do not claim to have kept up with upstream; do not block SURGICAL_FIX。

CREATE flow

Step 0 · Question the intent first (hard gate, scrutinize mode)

Before creating, mandatorily check three questions; first answer autonomously using catalog/project evidence, and ask only when the user's intent cannot be determined from the conversation:

Can itextend an existing skill? (Check for overlap from the current runtime's available-skills catalog and the project's local skill directory; do not guess installation paths)
Can itnot be built? (Is doing nothing acceptable? Is a manual one-off operation enough?)
Confirm that creation is necessary → proceed to Step 1

If 1 or 2 is answered yes → tell the user the alternative (which skill to extend / why it need not be built), and do not create it.

Step 1 · Capture intent

Extract from the conversation (or ask the user):

What does this skill enable the agent to do?
When is it triggered? (What keywords/scenarios will the user say?)
Expected output format?
Are scripts/ or references/ subdirectories needed?

If the user cannot explain clearly → stop, list the unclear parts, and wait for additions.Do not guess.

Step 2 · Research

Confirm Step 0's conclusion that "an existing one cannot be extended" (recheck the catalog and the current project). If an extensible one is found → return to Step 0.

Completion condition: Confirm creation and explain the reason

Step 3 · Write SKILL.md

Follow the skeleton template and writing rules below. First decide whether to use the minimal or full skeleton, then fill it in.

Completion conditions: The frontmatter conforms to the schema allowed by the target runtime (the common minimal set for Agent Skills is name + description; the laohan-local profile additionally requires version), and the main text and resource references are complete

Step 4 · Test iteration

First test in a writable working copy; install only if the target runtime requires installation, using its official path/packaging method, and do not automatically create symlinks
Trigger test: automatic routing Skill must cover at least one should-trigger and one near should-not-trigger; when there are many branches or the description changes substantially, expand to every branch; for purely manual invocation, record NOT_APPLICABLE
Execution test: for deterministic skills, use mechanically verifiable input/output fixtures; for subjective skills, use blind comparison and specific quality criteria
held-out validation: for complex, high-impact cases, or when the user requests comparison of effects, keep at least 1 sample not used for revision; for simple Skills, one real execution sample is enough
Repeated-work check: read the execution transcript; if the same auxiliary code is generated every time → extract it into scripts/
If it does not pass → go back to Step 3 to revise → retest
If it does not pass after 3 rounds → stop; it may be a structural problem rather than a minor fix, so re-examine the core idea

Step 5 · Local acceptance

Use real execution results to decide whether it is complete; the 6-dimension score is used only as a diagnostic when the structure is unclear or the user requests scoring
Complex/high-impact Skills require held-out non-regression; simple Skills can be accepted if the target samples and trigger tests pass
🔴 PUBLISH CHECKPOINT: perform the corresponding external action only when the user explicitly requests push/publish/package/install; creation or optimization itself does not imply publishing authorization

SKILL.md skeleton template

Not every Skill needs a complete skeleton. When the logic is simple enough to explain in a few lines, write the instructions directly; do not add extra sections for the sake of being "professional".

Criteria: single-step, no complex conditional branches (except simple fallback), no role distinction → minimal. Multiple steps/conditional branches/multiple roles → complete skeleton.

Minimal example (5 lines)

---
name: caveman
description: 极简回应模式，只输出关键信息。Use when 用户说"caveman mode""极简""少说废话""简短"。
---

所有回应控制在 3 句话以内。只给结论和关键依据，不解释过程。如果用户要求详细解释，恢复正常模式。

Complete skeleton template (v2 upgrade)

---
name: skill-name
description: 一句话说清做什么。Use when 用户说"触发词1""触发词2""触发词3"或提到[相关场景]。  # ≤1024字符，3-8触发词，第三人称
# version: 1.0  # 只在目标 runtime/profile 允许时加
---

# Skill 标题

一句话定位。

## 核心理念（复杂 skill 必加，简单可省）

为什么存在、遵循什么原则。先讲 why 再讲 how——比直接列步骤更有效。

## 工作流

### 1. [步骤名]
- 做什么
- **完成条件：** [怎么判断这步做完了]
- **🔴 CHECKPOINT：** [仅当该步有外部副作用、高风险或用户保留决策时填；否则删除]
- **🛑 STOP：** [强制停止条件]

### 2. [步骤名]
- 做什么
- **失败处理（只有存在复杂降级链时用三段式；单一安全 STOP 直接写 if-then）：**

  | 触发条件 | 一线修复 | 仍失败兜底 |
  |---------|---------|-----------|
  | [X 失败] | [Y] | [Z] |

### 3. [步骤名]
- 做什么
- **涉及外部动作 → 🔴 等用户确认再执行**

## 操作规则

跨步骤常驻约束：

- [规则1]
- [规则2]
- 遇到 [异常] → [怎么处理]（不静默跳过）

## 不适用场景（refuse to draft 硬拒绝，v2 升级）

- 场景 A → 改用 [其他 skill]
- **缺 [必要输入 X] → 列出缺什么并停，不硬编、不猜**（9arm post-mortem 模式）

## 反模式（复杂 skill 必加，v2 从可选升级）

❌ 差：
"[反例]"

✅ 好：
"[正例]"

## 输出格式（可选）

# [标题模板]
## [章节1]

Scoring system (6-dimension quick scorecard)

Condensed from darwin 9 dimensions (for the complete 9 dimensions see references/scoring-rubric.md). To score any skill:

#	Dimension	Weight	Scoring standard
1	frontmatter quality	10	name/description conform to the fields allowed by the target runtime; the description states both what it does and when to use it. The number of trigger words is a heuristic; do not pile on words just to reach 3-8
2	Workflow clarity	20	Numbered steps + clear completion conditions + clear inputs and outputs
3	Failure mode encoding ⭐	20	Covers failure surfaces that can really occur and affect results; when one safe STOP is enough, do not force a three-part table; only complex degradation chains require the three-part form
4	Checkpoint design ⭐	15	There is an explicit gate before external side effects, high risk, or decisions reserved for the user; autonomous/deterministic skills can also get full marks by explaining why there is no human gate; do not add fake checkpoints for the sake of format
5	Executable specificity ⭐	25	Specific parameters/formats/examples make it directly executable; deduct points only when soft words replace necessary decision rules; references, user output, and uncertain facts do not mechanically count as hits
6	Counterexamples and risk boundaries ⭐	10	Prevent misuse and dangerous actions that this skill could actually trigger; skills that do not involve git/deletion/release are not penalized for not listing these actions

Scoring: each dimension is scored 1-10, total score = Σ(dimension score/10 × weight), maximum 100.

cite or it didn't happen（9arm）: every deduction must cite a specific line number or passage from SKILL.md. Vague "this isn't good enough" is not allowed.

Score bands：

85-100: static structure can proceed to execution/held-out validation, which does not mean it is publishable
70-84: needs optimization (find the lowest dimension and improve it)
<70: structural problems, re-examine the core idea

AUDIT process

Freeze the audited file and the user's concerns, and read the original version, the current version, and the actual invocation boundary.
First find issues that would change triggering, execution, effects, or maintenance cost, then look at format; each finding cites a specific line, diff, or execution evidence.
Distinguish BLOCKING、BEHAVIOR_RISK、MAINTENANCE and NO_ISSUE, and do not treat the static score as the number of issues.
Output conclusions and minimal recommendations; do not modify files, install, or commit; when the user subsequently requests a fix, route to SURGICAL_FIX or OPTIMIZE。

SURGICAL_FIX process

Clarify the error, the original source of truth, and the behavior that should remain unchanged.
Only modify lines traceable to that error; preserve existing templates, method libraries, and validated effects, and clean up duplicate or contradictory rules produced by this change.
Run a targeted check that fails before the fix and passes after it; if existing mechanical contracts are affected, also run the corresponding contract regression.
Do not add scoring tables, blind judges, full trigger matrices, general frameworks, or new Skills for this small fix.
Report what was changed, what was verified, and which real effects still await proof through actual use.

OPTIMIZE process

Optimize an existing skill (only modify the self-developed laohan series; modify third-party forks after npx):

1. Establish a comparable baseline

The main agent looks for structural problems across the 6 dimensions,deductions cite line numbers
Freeze the baseline skill, target runtime, test samples, scorer, and success metrics; without these, do not claim "optimization"

2. One causal hypothesis per round

Each round fixes only one testable behavioral defect; when the same root cause involves multiple rubric dimensions, fix them all at once, and do not leave self-contradictions for the sake of "one dimension per round"
Apply bounded add/delete/replace in an uncommitted working copy, and record the hypothesis and change budget

3. Independent validation and held-out gate

For deterministic skills, use a frozen mechanical verifier to compare baseline/candidate; subjective outputs are compared blindly bya judge that does not know the version labels. When only doing a static audit, an independent judge can be used to catch self-contradictions, but do not treat 73.8% as absolute truth
Accept a candidate only when pre-registered metrics strictly improve, or when the primary metric is flat and the fix has been proven to address a high-risk defect; otherwise discard the uncommitted changes

4. Lightweight ratchet

Commit only after validation passes; if the user has already authorized it and the candidate has been committed separately, use git revertwhen it regresses, not a destructive reset
Stop after 2 consecutive held-out rounds with no substantial improvement, or one round that only improves the format score

5. Deep optimization routing (not done here)

When large-sample multi-round optimization is needed, read references/scoring-rubric.md and run the full 9 dimensions; if darwin-skill is already installed in the current catalog, you may also execute according to its held-out loop. Do not auto-install in the current task.

Operating Rules

Constraints common to all modes:

Stay concise: After writing, review item by item and delete instructions that do not affect the output
Lazy creation: Only create files/directories when there is content; do not first create empty structures as placeholders
Generalize rather than overfit: Do not make niche adjustments for a single use case
Explain the why: "Because A, therefore B" is better than "MUST do B"—LLMs are smart; giving reasons is more effective than hard rules (anthropics)
Match the target user's language: The laohan series defaults to Chinese, keeping technical terms in English
Keep the original name when updating: installed is research-helper then output the same name, not v2 (anthropics)

dim5 softened-wording review (only used during AUDIT/OPTIMIZE scoring)

Review only actionable instruction paragraphs: If the following wording replaces specific conditions/actions and appears ≥3 times, dim5 deducts ≥3 points; quotations, counterexamples, user output, or objective uncertainty do not count:

"suggest" / "may consider" / "depending on the situation" / "exercise flexibility" / "as the case may be" / "as appropriate" / "suitably"

Replace with specific instructions: "Do X" (imperative sentence + specific parameters/examples). For the full banned-word list, see references/blacklist-phrases.md.

Counterexample blacklist (new in v2, streamlined to 8 items in darwin)

When creating/optimizing, prohibited:

Do not treat self-assessment as acceptance — The same session may perform static diagnosis; deterministic candidate acceptance requires an independent mechanical verifier + held-out, and subjective candidates require a blind judge + held-out (when accepting OPTIMIZE/complex candidates)
Do not commit before evaluating — First compare in a working copy; only use it when the candidate has been separately committed and authorization has been granted git revert
Do not pile up redundancy to pad scores — Stop when the ceiling is reached (2 consecutive rounds with Δ<2 points)
Do not pass off static scores as acceptance scores — AUDIT may be marked STRUCTURE_ONLY; only OPTIMIZE effect-improvement conclusions must have baseline/with-skill/held-out behavioral evidence
Verify only one behavioral hypothesis per round — Do not forcibly sever the same root cause using rubric categories
Do not silently skip anomalies — If fallback fails, you must first inform the user

Inapplicable scenarios (refuse to draft, upgraded to a hard refusal in v2)

Create agent(agent ≠ skill) → use the target runtime's agent configuration mechanism
Platform plugins not compatible with SKILL.md/Agent Skills → use that platform's native plugin specification
Modify npx third-party skill → create a new one after forking (npx skills update overwrite in-place changes)
Missing necessary input(the user cannot clearly say what to do) → list what is missing and stop, do not hard-code, do not guess (9arm refuse to draft)

Writing Rules

Frontmatter

---
name: skill-name          # kebab-case，与目录名一致
description: 功能描述。Use when 触发场景列举。  # ≤1024字符，第三人称
# version: 1.0            # 只在目标 runtime/项目 schema 允许时使用；laohan-local 要求
---

name + description are the persistent metadata by which the agent routes the skill. description must contain:

Function description (what it does in one sentence)
"Use when" + natural-language trigger scenarios sufficient to distinguish similar skills; 3-8 is a laohan-local heuristic, not a hard constraint of the general schema
Third person (mattpocock)
If there are competing skills, distinguish them explicitly

Body writing approach

Rules	Notes
Length control	Based on loading completely with no redundancy; keep it <500 lines when possible, and when approaching/exceeding that, split long references and detailed eval flows into references/
Core idea first	For skills with 3 or more steps, add a core idea section before the workflow (why before how)
Separate workflow and operating rules	Workflow = sequence of steps; operating rules = cross-step constraints, in a separate section
Stage gating	Set hard gates only before external side effects, high risk, or user-reserved decisions; do not add fake CHECKPOINTs for deterministic internal steps
Anti-pattern WRONG/RIGHT	Use contrast blocks for core rules (❌bad/✅good)
Mantra embedding (verbatim)	Use only when the task truly needs memorizable discipline; do not apply the debug-mantra form to every skill
Output format	Define with templates, do not give vague instructions
Fallback cascade	For multiple options, use strict priority order (try in sequence), not a menu
Cross-skill invocation	After completion, offer connect to another skill (no automatic handoff, 9arm post-mortem)
Writing principles	Imperative sentences + concrete examples + no ALL CAPS ALWAYS/NEVER + define tone for content-creation types
scripts/ criteria	Deterministic operations/repeatedly generated identical code/needs explicit error handling → scripts (mattpocock)
references/ criteria	Platform-specific methods/long templates/background knowledge that does not need to load every time → references (one level deep only)

Progressive disclosure (anthropics): metadata (always resident) → SKILL.md body (loaded when triggered) → bundled resources (as needed). Do not cram everything into SKILL.md; split heavy parts into references/scripts.

6-item minimal self-check list (quick pass after CREATE)

description includes Use when + trigger words
Keep SKILL.md <500 lines when possible; when exceeded, it must be split into references, and 100-500 lines is judged by loading value
No time-sensitive information (specific dates/version numbers unless necessary)
Consistent terminology
Has concrete examples
references are only one level deep

Acceptance and release checklist

After creation/optimization is complete:

SKILL.md is well written, frontmatter conforms to the target runtime schema (common minimal set name + description; laohan-local also has version)
The target runtime/profile is explicit, and the install path or packaging method comes from the current host spec
This mode has been recorded;AUDIT stays read-only,SURGICAL_FIX has not been upgraded to full optimization
CREATE/OPTIMIZE trigger, anti-trigger, and execution tests pass; SURGICAL_FIX targeted regression passes
Duplicate-work check (no identical helper code generated every time)
Only OPTIMIZE or complex/high-impact CREATE requires held-out; only subjective comparisons require a blind judge
The runtime scan runs according to the profile; fatal issues must be fixed, and for portable-specific path warnings, humans determine whether a capability branch already exists
When modifying this Skill itself, it has already been run scripts/check-upstreams.sh, and update the upstream record according to the actual verification results
Security check passed (no API key/personal absolute path, release actions have explicit authorization)
Local commit, install, package, push, and publish are registered separately; local commit follows the authorization of the current task/repository, while install, package, push, and publish are executed only with the user's explicit authorization