mirror of
https://github.com/getsentry/skills.git
synced 2026-09-14 20:00:03 +08:00
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>
67 lines
3.3 KiB
Markdown
67 lines
3.3 KiB
Markdown
# 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](../plugins/sentry-skills/skills/skill-writer/SKILL.md) 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](https://agentskills.io/specification) | The spec — frontmatter fields, structure, constraints |
|
|
| [Anthropic's official skills](https://github.com/anthropics/skills) | Anthropic's reference implementations |
|
|
| [OpenAI Codex's skills](https://github.com/openai/skills) | OpenAI's approach to the same problems |
|
|
| [Skills best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) | Claude's guidance on writing effective skills |
|
|
| [Claude Code skills docs](https://code.claude.com/docs/en/skills) | 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](../README.md#vendoring-skills).
|
|
- **One skill at a time.** Synthesizing multiple skills in one session gets messy.
|