1. First decide: does this content deserve to be a skill
| Judgment | Destination |
|---|---|
| Will repeat across machines/projectsMethod(how to do it, how to avoid pitfalls) | skill |
| Only holds for this machine/this projectFact(path, version, state) | Memory system or host-layer documentation, not a skill |
| One-off task, hasn't happened a second time yet | Write nothing, wait for it to repeat |
| General knowledge the agent already has | Don't write; a skill only writes the differences it doesn't know (exact key names/commands/version lines/pitfalls) |
A general method mixed with local-machine facts → when writing it as a skill, placeholder-ize it ({{路径}}), local-machine values go into the host layer or memory; platform-environment-skill-audit governs the desensitization bottom line for backflow.
2. Shaping (think it through before writing)
- Naming: kebab-case, verb or noun phrase, ≤64 characters, directory name = name; the prefix can align with the family (exp-、accel-）。
- Where to put it: repo base group (common to all machine types) / accel group (compute scenarios) / local machine
~/.agents/skills/(only this machine). Remember to add ones that go into the repo to the corresponding list in the setup script (selfcheck will check). - Division of labor: write the boundary with adjacent skills in one sentence in the description ("use X to install the environment, use this skill to write code"), to avoid double triggering or no triggering at all.
- Evolution nature: set the tier when writing, and make the update convention explicit.
| Tier | Applicable | Update convention |
|---|---|---|
| Experience-evolving type | kb-*、personal-ui-taste | State the update trigger, content, and backflow method; for knowledge record date + evidence, for taste record evolution |
| Fact-frozen type | accel trio | Specialize once at installation; backflow the same day, then leave it unchanged |
| Fixed-instruction type | One-off process | No evolution, discarded once expired |
Installation strategy: evolving type can be overwritten and refreshed; frozen type is installed only once.
3. description (the field that determines life or death)
- Third person or imperative,what + when + trigger words: what it does, when to use it, how the user will refer to it (including Chinese colloquial trigger words).
- Write only what is needed for triggering, not implementation details; ≤1024 characters.
- Counterexample: "handle files" (matches no phrasing); positive example: "Extract text and tables from PDF files. Use when working with PDF files or when the user mentions PDFs, forms".
4. Body (high entropy, blunt, strongly guiding)
- Limit ~150 lines; keep only information that affects execution; don't cram multiple key points into one line just to reach a line count.
- Separate steps from reference: inline the steps in SKILL.md; push lookup tables and things needed only in some branches to ancillary files in the same directory, with pointers only one level deep.
- Every step has a completion criterion: What is the sign that this step is done (an observable output/state); a step without a criterion is a pointless step.
- Give degrees of freedom by fragility: For error-prone spots, give exact commands (copy-paste runnable); for judgment spots, give a one-sentence heuristic; don't give a menu and let the agent pick.
- Details = points of difference: Exact commands, key names, version lines, real pitfalls actually hit (symptom → cause → handling); delete common knowledge, lead-ins, repeated explanations, and keep the conditions, reasons, and exceptions that affect judgment.
- leading words: The same concept narrated repeatedly in three places → converge into a single guide word; every redundant sentence is debt for the next maintenance.
- Time-sensitive content carries a date(version lines, matrices); mark unverified ones as
(未验证); don't hard-code conclusions that will expire without giving a re-check command. - Primarily Chinese, following readable-docs: prefer phrases, use full sentences as needed, paragraphs as the exception; one item one meaning in lists, write only the differences in comparison table cells.
5. Final check (self-check after writing)
- Trigger test: Simulate with 2–3 real user phrasings; will the description hit? Will an adjacent skill grab it?
- Information and skimming check: What more can be deleted without losing meaning? Check the longest items and split them into separate points; don't delete content based on the length ratio of explanations to code.
- De-contextualization check: grep for local traces (usernames/host paths/IPs); use placeholders where placeholders are due.
- First real use: A skill's value is verified the second time it is triggered; if used wrongly, change the description; if missed, add trigger words; don't pre-design branches that won't be used (YAGNI).
6. Evolution
Fixed loop: modify the local copy on the real machine → download to the dev machine → merge into the repo and push → each machine pulls the new version.
- Landing point: the minimal change goes back into the skill body, without changing the structure; when a rule is overturned, update the corresponding subsection and note the evidence.
- Refresh: refresh groups are refreshed automatically; install-once groups are explicitly reinstalled.
- Loss prevention: before local modifications have flowed back, don't re-run setup's overwrite refresh.
| Category | Evolution protocol |
|---|---|
| Knowledge type (kb-*) | Record date + evidence per its "Evolution" section |
| Compute platform type | accel-skill-template write-to-disk rules |
| Taste type | personal-ui-taste evolution protocol |