writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- writing-skills
- description
- Use when creating new skills, editing existing skills, or verifying skills work before deployment
02 资源文件 1
- 参考文档testing-skills-with-subagents.md2.7 KB
03 SKILL.md 正文
Writing Skills
Purpose
Create the smallest reusable skill that changes decisions or improves task
execution without constraining unrelated work. Skill changes use behavior
validation, not a code TDD route. This validation does not require loading aegis:test-driven-development.
Default Path
1. Establish Need And Ownership
- Name the reusable behavior gap, intended users/hosts, and non-goals.
- Check whether an existing skill, project rule, host adapter, or automated check already owns it. Prefer the smallest existing owner.
- For an existing skill, inspect its references, manifests or generated copies, discovery tests, and bundled resources before changing or retiring them.
- Create a skill only for reusable, non-obvious guidance. Keep one-off project conventions in the project owner and automate mechanical constraints when practical.
2. Record Behavior Before Editing
Use representative tasks, not questions that merely ask the agent to recite instructions.
- New skill: run a no-skill control.
- For an existing skill, run the current version first; add a no-skill ablation only when testing whether the skill itself needs to exist.
- Cover positive triggers, negative near-misses, and a pressure or application case appropriate to the skill type.
- Record decisions, missed or extra invocations, unsafe workarounds, evidence references, and unknowns. Do not treat line or byte counts as behavior proof.
If meaningful behavior cannot be evaluated, stop at needs-verification; do
not claim that the skill is deployment-ready or capability-preserving.
3. Design The Minimum Instruction Surface
- Assume the agent is capable. Include only non-obvious context, decision criteria, safety boundaries, and steps whose omission caused an observed gap.
- Match specificity to risk: allow judgment for open work; use exact sequences only for fragile, permission-sensitive, or safety-critical operations.
- Keep the description concise, third-person, and discriminating. State the capability and when it applies; add an exclusion only when it prevents likely misrouting. Do not turn the description into a procedural shortcut.
- Keep the executable default path and non-omittable constraints in
SKILL.md. Move substantial conditional detail to a direct reference and state the evidence trigger for reading it. - Keep references one level deep where practical. Do not load every reference by default or duplicate its content in the main body.
- Add an example only when it materially stabilizes a decision or output. One representative example is normally enough.
- Keep portable method instructions host-neutral. Put host tool names, install paths, and UI choreography in their host-owned documentation.
The canonical repository shape is skills/<skill-name>/SKILL.md with only the
supporting references, scripts, or assets the workflow actually uses. Use the
repository's host docs or the target host's live specification for optional
metadata instead of copying a vendor manual into the skill.
4. Make The Smallest Change
Address observed gaps and remove superseded duplication in the same slice.
Preserve public attribution and any externally supported contract. When
retiring an internal owner, fallback, or resource, compose
aegis:anti-entropy-governance; do not leave a compatibility copy without
dependency evidence.
Do not convert one model's phrasing, one historical incident, or a hypothetical edge case into a universal rule.
5. Validate The Candidate
Re-run the same positive, negative, and pressure/application scenarios under a comparable model, tool, and host configuration. Compare outcomes, not wording.
Also verify:
- frontmatter, name, and description parse on supported hosts;
- intended requests still discover the skill and near-misses do not;
- every conditional reference is reachable from an explicit trigger;
- changed scripts run successfully;
- retired files and instructions have no live references;
- repository workflow, boundary, packaging, and host checks relevant to the touched surface pass.
If behavior regresses, restore the missing obligation or narrow the change; do not add a second owner or fallback to mask it.
Scenario Selection
| Skill type | Representative evidence |
|---|---|
| Discipline or safety | realistic pressure and authorization boundaries |
| Technique | application, variation, and missing-information cases |
| Pattern | recognition, application, and counter-example cases |
| Reference | retrieval, correct use, and common-gap cases |
For a complex or high-risk skill where an independent evaluator adds confidence,
read testing-skills-with-subagents.md.
Completion Record
Keep the result compact and auditable in natural prose or equivalent fields:
- behavior gap and canonical owner;
- baseline and candidate scenario results;
- retained and retired obligations/resources;
- trigger and reference checks;
- verification commands and uncovered hosts/models;
- status:
verified,needs-verification, orblocked.
This is method-pack evidence, not authoritative completion or deployment approval.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.