diff --git a/skill-standard/SKILL.md b/skill-standard/SKILL.md index ac310a1..a8d747d 100644 --- a/skill-standard/SKILL.md +++ b/skill-standard/SKILL.md @@ -1,88 +1,109 @@ --- name: skill-standard -description: The authoritative quality standard for writing SKILL.md files. Use this to evaluate, audit, or improve any skill's content. +description: Meta-standard for classifying skills before applying the correct quality rubric. Use this to decide whether a skill is workflow-oriented or strategy-oriented, then switch to the matching standard. --- # Skill Standard -The authoritative reference for what makes a skill well-written. Use this when writing a new skill, auditing an existing one, or improving SKILL.md content quality. +This is the routing standard, not the only writing standard. ---- - -## Skill Writing Standard - -**Every SKILL.md MUST follow these principles:** - -### 1. Semantically Clear, No Ambiguity - -Every word in a SKILL.md must have a single clear meaning. Avoid vague terms that could be interpreted multiple ways. +Use this skill to classify a skill into the correct category before judging its quality. +A single universal rubric is not sufficient for all SKILL.md files. -- ✅ "Search for major AI model releases (new versions from OpenAI, Anthropic, Google, Meta)" -- ❌ "Update model" (update which model? update how? update the AI model itself, or update info about models?) +--- -### 2. Goal-Oriented, Not Step-by-Step +## Core Rule -Tell the AI **what** to achieve, not **how** to execute. The AI can figure out commands, file discovery, and execution order on its own. +Before evaluating or rewriting any skill, first decide what kind of skill it is. -- ✅ "Complete the daily check-in and fetch sign record to verify" -- ❌ "Run `python3 -m checkin.xiaojuchongdian.src.main run --task xiaoju.checkin --verify-record`" +There are at least two major categories: -### 3. Declare Available Tools, Don't Dictate Usage +1. **Workflow Skills** + - execution-oriented + - meant to get a task done + - usually have concrete success/failure conditions + - often back cron jobs, automation, API tasks, or operational flows -If the skill has programmatic assets (scripts, CLI tools, APIs), describe **what they do** and **where they are** relative to the skill. Let the AI read the code and decide how to use them. +2. **Strategy Skills** + - reasoning-oriented + - meant to give a framework, doctrine, checklist, or evaluation method + - usually guide judgment rather than execute a fixed flow + - often support review, writing, planning, or auditing work -- ✅ "Entry point: `main.py`. Read the file to understand usage." -- ❌ "Run `python3 -m checkin.xiaojuchongdian.src.main status --task xiaoju.checkin`" +Do not apply one category's rubric to the other category by default. -### 4. Portable Paths Only +--- -Never hardcode absolute or repo-root-relative paths. Use paths relative to the skill itself. +## Classification Heuristic + +### Choose **Workflow Skill** when the skill primarily answers: +- What concrete task should be completed? +- What assets or runtime are available to complete it? +- What counts as done? +- What should happen when runtime conditions fail? + +Typical examples: +- check-in flows +- changelog collection +- auth refresh flows +- scheduled automation +- API-driven operational tasks + +### Choose **Strategy Skill** when the skill primarily answers: +- How should the model think about this class of problem? +- What principles or decision criteria should it use? +- What anti-patterns should it avoid? +- When should this framework be applied or not applied? + +Typical examples: +- review rubrics +- writing heuristics +- evaluation standards +- architectural judgment frameworks +- planning/doctrine/checklist skills -- ✅ "Located in the `scripts/` directory of this skill" -- ❌ "Location: `checkin/xiaojuchongdian/skill/get-params/scripts/`" +--- -### 5. Know What AI Can and Cannot Do +## Routing Rule -**AI can figure out on its own** (don't over-specify): -- How to run a Python/Shell/Node script after reading it -- Which subcommands or flags a CLI supports -- How to parse JSON output -- How to find files in a directory -- Error handling and retry logic +After classification: -**AI needs to be told** (must specify): -- The goal and success criteria -- What programmatic assets exist and their purpose -- Key constraints (auth requirements, idempotency, user interaction needed) -- Dependencies on other skills (by skill name, not path) +- If it is execution-oriented, use `workflow-skill-standard`. +- If it is reasoning/framework-oriented, use `strategy-skill-standard`. -### 6. Reference by Skill Name, Not Path +If a skill mixes both categories, identify its primary role first. +Only then decide whether to: +- keep it hybrid intentionally, or +- split it into a workflow skill plus a strategy skill. -Skills depend on each other by **name**. OpenClaw resolves names to locations. +--- -- ✅ "Use the `xiaoju-get-params` skill to refresh credentials" -- ❌ "Switch to `checkin/xiaojuchongdian/skill/get-params/SKILL.md`" +## Anti-Patterns -### 7. Declare Dependencies in skill.json +### Wrong: workflow rubric forced onto strategy skills +Symptoms: +- over-constraining an evaluation rubric with rigid execution gates +- demanding procedural completion signals from a doctrine/checklist skill +- turning judgment frameworks into brittle pseudo-SOPs -External or sub-skill dependencies must be declared in `skill.json` under `sub_skills` (by skill name), so OpenClaw can auto-install them. +### Wrong: strategy rubric forced onto workflow skills +Symptoms: +- goals sound good but execution contract is vague +- runtime constraints are implied instead of specified +- completion is left to model intuition +- automation can "look done" without being verifiably complete -### 8. Declare Explicit Completion Signals +--- -For any task, define an explicit completion signal tied to a verifiable standard — not to the model's own sense of sufficiency. **"Looks done" is not done. Completion means the defined criteria are met and verified.** +## Output -**Warning Signs** — if you think any of these, pause and take the correct action: +When using this skill, produce: +1. the detected skill category +2. the reason for classification +3. the correct downstream standard to apply +4. if needed, whether the skill should be split into two skills -| Thought | Reality | Correct Action | -|---|---|---| -| "I've read enough to understand" | Read = read every item in scope. Partial reads are not reads. | Enumerate all items, then read each one. | -| "I've seen most of the nodes/files" | Most ≠ all. | List all items first, then process them in order. | -| "This looks like a standard structure" | Assumptions replace reading. | Read the actual content before drawing conclusions. | -| "The fix is small, checking is overkill" | Small fixes break adjacent behavior. | Verify the full scope before and after the fix. | -| "I've covered the main cases" | Main cases ≠ all cases. | Explicitly check for edge items before closing. | -| "I've completed the task" | Completion ≠ verified to the highest standard. Reading all nodes does not mean spacing, hierarchy, and every property has been validated. | Validate every property against the full spec before declaring done. | +## Completion Signal -**How to write completion signals in a skill:** -- ✅ "Read all child nodes before generating output. Do not assume the structure from partial traversal." -- ✅ "Verify every item in the list is processed. Log skipped items explicitly." -- ❌ (no completion signal stated — model decides when it's done) +Do not stop at “this skill looks fine.” +A completed review must explicitly name the skill category and the correct standard that should govern it. diff --git a/strategy-skill-standard/SKILL.md b/strategy-skill-standard/SKILL.md new file mode 100644 index 0000000..367a730 --- /dev/null +++ b/strategy-skill-standard/SKILL.md @@ -0,0 +1,88 @@ +--- +name: strategy-skill-standard +description: Quality standard for reasoning-oriented skills that provide frameworks, rubrics, heuristics, or decision guidance. +--- + +# Strategy Skill Standard + +Use this standard for skills whose primary job is to shape how the model thinks. + +These skills are not execution contracts first. +They are judgment frameworks. +Their quality depends on clarity of scope, principles, and decision boundaries. + +--- + +## What a Strategy Skill Must Do + +A strategy skill must define: +- what kind of problem it helps with +- when it should be used +- when it should not be used +- what principles or criteria should guide judgment +- what anti-patterns or traps to avoid + +If it does not define those boundaries, it will sprawl and be misapplied. + +--- + +## Strategy Writing Standard + +### 1. Purpose and scope must be explicit +State the class of decisions this skill is for. +Do not pretend to be universal if the framework is only useful in a narrow domain. + +### 2. Principles over pseudo-procedure +A strategy skill should provide decision rules, criteria, and heuristics. +Do not force it into fake operational steps unless the strategy genuinely requires staged analysis. + +### 3. Tell the model what to notice +A good strategy skill highlights the important dimensions to evaluate. +Examples: +- evidence quality +- ambiguity level +- tradeoff boundaries +- common failure modes +- escalation conditions + +### 4. Define applicability boundaries +The skill must explain when to use it and when another skill or framework is more appropriate. +Without this, strategy skills become vague universal advice. + +### 5. Anti-patterns are first-class content +A strong strategy skill explicitly names the common wrong moves. +This is often more important than adding more principles. + +### 6. Do not fake workflow completion signals +A strategy skill usually should not pretend to have operational completion gates like a workflow skill. +Its completion signal should instead be tied to whether the correct reasoning frame was applied and the relevant criteria were evaluated. + +### 7. Abstraction must stay grounded +The framework should be reusable, but still concrete enough to guide real decisions. +If everything sounds wise but nothing changes behavior, the skill is too abstract. + +--- + +## Anti-Patterns + +- reads like motivational advice instead of a usable framework +- no scope boundary, so it applies to everything and therefore nothing +- no anti-patterns, so misuse is invisible +- over-converted into rigid steps that kill judgment +- vague slogans replace decision criteria + +--- + +## Review Output + +When auditing a strategy skill, report: +1. the intended decision domain +2. whether scope is clear +3. whether principles are concrete enough to guide judgment +4. whether anti-patterns are explicit +5. whether applicability boundaries are defined +6. the exact ambiguity or overreach, if any + +## Completion Signal + +A strategy skill review is complete only when you can state what problems the skill is for, what decision criteria it provides, and where its boundary stops. diff --git a/workflow-skill-standard/SKILL.md b/workflow-skill-standard/SKILL.md new file mode 100644 index 0000000..c058aa6 --- /dev/null +++ b/workflow-skill-standard/SKILL.md @@ -0,0 +1,110 @@ +--- +name: workflow-skill-standard +description: Quality standard for execution-oriented skills that run tasks, automation, APIs, or operational workflows. +--- + +# Workflow Skill Standard + +Use this standard for skills whose primary job is to get something done. + +These skills are execution contracts. +They must be clear enough that the model and runtime can complete the task without inventing missing rules. + +--- + +## What a Workflow Skill Must Do + +A workflow skill must define: +- the task goal +- the available assets or runtime used to complete it +- the critical constraints +- the dependency relationships +- the completion signal +- the failure boundary + +If any of those are vague, the skill is incomplete. + +--- + +## Workflow Writing Standard + +### 1. Goal-first, execution-focused +State the task outcome clearly. +The goal must describe what the task accomplishes in the real world, not just what command might run. + +### 2. Describe assets, not hand-holding commands +Declare the programmatic assets that exist and what they can do. +Do not over-script exact execution unless a literal command is itself part of the contract. + +### 3. Runtime contract must be explicit +If the task depends on auth, env, local files, APIs, services, or scheduling context, say so clearly. +Do not rely on implied runtime assumptions. + +Examples of runtime contract items: +- required auth fields +- config source of truth +- isolated runtime behavior +- idempotency expectations +- side-effect boundaries + +### 4. Dependencies must be named +If the skill relies on another skill, reference it by skill name. +Its `skill.json` must declare that dependency when applicable. + +### 5. Success must be externally verifiable +A workflow skill must define completion in terms of observable state. +Do not let the model decide that “it probably worked.” + +Good completion signals: +- platform state confirms today is signed +- output contains validated record data +- required downstream artifact exists and passes checks + +Bad completion signals: +- task ran without crashing +- output looks plausible +- model thinks enough steps were done + +### 6. Failure states must be explicit +A workflow skill must say what failure looks like. +Examples: +- missing required config +- invalid credentials +- platform rejected the action +- verification failed + +### 7. Idempotency must be stated when relevant +If repeated execution is safe, say so. +If repeated execution is unsafe, say so. +Do not leave this implicit. + +### 8. Recovery path must be clear +If the normal path can fail due to known preconditions, specify the recovery route. +Example: +- use `xiaoju-get-params` when auth is missing or invalid + +--- + +## Anti-Patterns + +- commands dominate the skill while runtime assumptions stay vague +- success means “the script was called” instead of “the platform state was verified” +- missing distinction between execution start and execution qualification +- no defined behavior when credentials/config are unavailable +- cron/isolated runtime assumptions left implicit + +--- + +## Review Output + +When auditing a workflow skill, report: +1. whether the goal is clear +2. whether runtime contract is explicit +3. whether dependencies are declared +4. whether completion signal is verifiable +5. whether failure/recovery paths are defined +6. the exact ambiguity or gap, if any + +## Completion Signal + +A workflow skill review is complete only when you have checked goal, runtime contract, dependency model, success criteria, and failure criteria explicitly.