authoring-skills-from-scratch
Guides users through writing a strong skill: trigger conditions, core guidance, examples, anti-patterns.
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 4
- Forks
- 0
01 前言 Front Matter
- name
- authoring-skills-from-scratch
- version
- 1.0.0
- category
- Ops
- description
- Guides users through writing a strong skill: trigger conditions, core guidance, examples, anti-patterns.
02 资源文件 1
- 参考文档notes/authoring-skills.md4.0 KB
03 SKILL.md 正文
Authoring Skills from Scratch
A skill is behavioral guidance for the AI harness — domain-specific instructions loaded into context to shape how the harness approaches specific types of work.
What makes a strong skill?
When to use — Trigger conditions: what types of tasks or code patterns activate this skill. Good: "When creating or reviewing feature flags in PostHog or code." Bad: "When working on the backend."
Core guidance — Behavioral rules the harness should follow. Prescriptive, not suggestive. Good: "Flag names follow the pattern feature_<name>_<variant>." Bad: "Consider using a consistent naming pattern."
Concrete examples — Real code or configuration showing the pattern in action. 2–3 examples minimum. Good: feature_passwordless_auth_alpha. Bad: No examples, only prose.
Anti-patterns — What NOT to do, with explanations of why. Often more valuable than positive guidance. Good: "ff_auth_v2 — too cryptic, doesn't follow naming pattern." Bad: Omitted.
How to write one
- Define trigger conditions first: What types of tasks or code patterns should activate this skill? Be specific — name the tools, file paths, or task types.
- Write core guidance as prescriptive rules: "Always do X" is better than "consider doing X." Each rule should be a single, testable instruction.
- Add 2–3 concrete examples: Show the pattern in real code or configuration. Examples should be copy-pasteable and recognizable.
- Document anti-patterns: What should the harness NOT do? Why? For each anti-pattern, explain the failure mode it prevents.
- Test the skill: Load it and give the harness a task that should trigger it. Does it follow the guidance? If not, tighten the trigger conditions or rules.
Keep the skill under ~2000 words. If it exceeds that, it's probably covering multiple domains — split it.
Common mistakes
- Too long, covering multiple domains. A skill for "all of backend development" is too broad; create separate skills for "NestJS patterns," "BullMQ job queues," etc.
- Vague guidance. "Consider" and "think about" are not instructions. Use "always," "never," "must."
- No examples. Without concrete examples, the harness applies the rules inconsistently.
- Duplicating blueprint content. Skills guide behavior; blueprints describe state. A skill says "follow this pattern when writing API routes." A blueprint says "our API routes use this pattern because we decided X."
- No trigger conditions. Without triggers, the harness doesn't know when to load the skill.
Prompts to get unstuck
- "What tasks should activate this skill?"
- "What's the one rule the harness must follow?"
- "Show me a real example of this pattern."
- "What mistake does the harness make without this skill?"
04 同仓库更多 Skills
writing-waterfall-requirements-documents
Write a waterfall requirements document: elicit, structure and review testable, traceable requirements, then baseline the specification before design.
writing-vision-and-values-statements
Write a V2MOM vision a reader can test and a ranked list of values that settles real tradeoffs, so the rest of the document has a clear anchor.
writing-system-prompts-for-claude
Write Claude prompts and CLAUDE.md files that supply exact inputs, scope the task, and define done so the first attempt can be checked.
writing-page-specific-website-copy
Website copywriting by page type: write homepage, landing page, pricing page and feature page copy that fits each page's visitor and single job.
writing-internal-press-releases
How to write an internal press release: the one-page working backwards press release that opens a PR/FAQ document before anything is built.
writing-email-sequences-that-sell
Email sequence copywriting for nurture and sales: give each email one job, write clear subject lines, and close with one specific call to action.