David Cramer
942b2c1421
* ref(skills): Rename PR and skill authoring workflows Promote pr-writer and skill-writer as canonical skill names while\nkeeping create-pr and skill-creator as compatibility aliases.\n\nUpdate skill registration, settings allowlists, and documentation\nreferences to prefer canonical names.\n\nExtend skill-writer guidance with capability-first naming practices\nand examples for clearer skill discovery. Co-Authored-By: GPT-5 Codex <noreply@openai.com> * fix(skills): Address review bot feedback on skill rename Restrict skill-writer with an explicit allowed-tools frontmatter field,\nremove dead code in quick_validate, and delete orphaned duplicate\nreferences/scripts from the skill-creator alias directory to avoid drift. Co-Authored-By: GPT-5 Codex <noreply@openai.com> * fix(skills): Drop allowed-tools from skill-writer Keep skill-writer frontmatter compatible across clients by avoiding\nthe optional allowed-tools field while retaining the other review\nfixes in this PR. Co-Authored-By: GPT-5 Codex <noreply@openai.com> * docs(skill-writer): Default to omitting allowed-tools Clarify that skill authoring should avoid allowed-tools unless a user\nexplicitly requests strict tool scoping or repo policy requires it,\nsince allowlist syntax differs across clients. Co-Authored-By: GPT-5 Codex <noreply@openai.com> * docs(pr-writer): Include update flows in skill discovery text Expand pr-writer trigger language to explicitly cover updating PR artifacts\nlike title and description, not only creating a new PR.\n\nAlso align the README skill table description so repository docs\nmatch the canonical skill wording. Co-Authored-By: GPT-5 Codex <noreply@openai.com> --------- Co-authored-by: GPT-5 Codex <noreply@openai.com>
3.3 KiB
Skill Synthesis Guide
Skill synthesis is using your AI coding agent to research upstream implementations, specs, and best practices online before creating a skill. Instead of writing from scratch, you have the agent survey what already exists and synthesize the best ideas into your skill.
This pairs with the skill-writer skill — synthesis handles the research phase, skill-writer handles the implementation.
Key Sources
Point your agent at these when researching:
| Source | What it covers |
|---|---|
| Agent Skills Specification | The spec — frontmatter fields, structure, constraints |
| Anthropic's official skills | Anthropic's reference implementations |
| OpenAI Codex's skills | OpenAI's approach to the same problems |
| Skills best practices | Claude's guidance on writing effective skills |
| Claude Code skills docs | How skills integrate with Claude Code |
Not every source is relevant to every skill. If you're creating a code review skill, look for upstream code review skills. If you're creating something novel, focus on the spec and best practices.
The Workflow
1. Research — tell the agent what to look for
Give the agent the concept and ask it to research before writing anything:
I want to create a skill for Django performance reviews. Before writing it,
research upstream implementations — check Anthropic's and OpenAI's skill repos
for anything similar, read the Agent Skills spec, and look at the best practices
docs.
The agent will fetch sources, cross-reference approaches, and report back what it found.
2. Review — understand what the agent found
The agent should show you:
- What patterns it found upstream worth adopting
- What's unique to our context that upstream skills don't cover
- How it recommends structuring the skill
This is your checkpoint. Redirect before writing, not after.
3. Create — hand off to skill-writer
Once you agree on the approach, use the skill-writer to build the skill informed by the research:
Now use /skill-writer to create the skill, incorporating what you found.
The synthesis research stays in context, so the skill-writer produces a better result than it would from a cold start.
When To Do This
- Creating any non-trivial skill — if upstream implementations exist, research them first
- Porting a skill from another repo — understand the original before adapting
- Rebuilding a skill — when a rewrite is needed, check the current state of the art
Tips
- Research before writing. The whole point is that the agent creates a better skill because it looked at what already exists.
- Review the research, not just the output. Understand what the agent pulled from where — some upstream patterns won't fit your context.
- Check attribution. If the agent adopts patterns from a specific upstream skill, follow the vendoring guidelines.
- One skill at a time. Synthesizing multiple skills in one session gets messy.