feat(skill-creator): Add skill synthesis guide and upstream best practices

README.md

@@ -228,6 +228,7 @@ The `code-simplifier` agent is vendored from [Anthropic's official plugins](http
 
 - [Agent Skills Specification](https://agentskills.io/specification)
 - [Sentry Engineering Practices](https://develop.sentry.dev/engineering-practices/)
+- [Skill Synthesis Guide](docs/skill-synthesis.md) — using your AI agent to research and improve skills
 
 ## License
 

docs/skill-synthesis.md

@@ -0,0 +1,66 @@
+# 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-creator](../plugins/sentry-skills/skills/skill-creator/SKILL.md) skill — synthesis handles the research phase, skill-creator 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-creator
+
+Once you agree on the approach, use the skill-creator to build the skill informed by the research:
+
+```
+Now use /skill-creator to create the skill, incorporating what you found.
+```
+
+The synthesis research stays in context, so the skill-creator 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.

plugins/sentry-skills/skills/skill-creator/SKILL.md

@@ -1,12 +1,17 @@
 ---
 name: skill-creator
-description: Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, writing, registration, and verification.
+description: Create new agent skills following the Agent Skills specification. Use when asked to "create a skill", "add a new skill", "write a skill", "make a skill", "build a skill", or scaffold a new skill with SKILL.md. Guides through requirements, planning, writing, registration, and verification.
 ---
 
 <!--
 Adapted from skill-creator implementations by Anthropic and OpenAI:
-https://github.com/anthropics/claude-plugins-official
-https://github.com/openai/codex-plugins-official
+https://github.com/anthropics/skills/tree/main/skills/skill-creator
+https://github.com/openai/skills/tree/main/skills/.system/skill-creator
+
+References:
+- Agent Skills specification: https://agentskills.io/specification
+- Skill authoring best practices: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
+- Validation library: https://github.com/agentskills/agentskills/tree/main/skills-ref
 -->
 
 # Create a New Skill
@@ -19,13 +24,15 @@ Gather requirements before writing anything.
 
 **Ask the user:**
 1. What should this skill do? (one sentence)
-2. When should an agent use it? (trigger phrases)
+2. When should an agent use it? (trigger phrases users would say)
 3. What tools does the skill need? (Read, Grep, Glob, Bash, Task, WebFetch, etc.)
 4. Where should the skill live? (which plugin or directory)
 
 **Determine the skill name:**
-- Lowercase alphanumeric with hyphens, 1-64 characters
+- Lowercase letters, digits, and hyphens only (`a-z`, `0-9`, `-`)
+- 1-64 characters; must not start or end with `-`; no consecutive hyphens (`--`)
 - Descriptive and unique among existing skills
+- Prefer action-oriented names: `processing-pdfs`, `fix-issue`, `code-review`
 - Check the target skills directory to avoid name collisions
 
 **Choose a complexity tier:**
@@ -39,15 +46,29 @@ Gather requirements before writing anything.
 
 Read `${CLAUDE_SKILL_ROOT}/references/design-principles.md` for guidance on keeping skills focused and concise.
 
-## Step 2: Study Existing Skills
+## Step 2: Plan the Skill
+
+Analyze how each use case would be executed from scratch. Identify what reusable resources would help when executing these tasks repeatedly.
+
+For each concrete example, ask:
+1. What code would be rewritten every time? → candidate for `scripts/`
+2. What documentation is needed to inform decisions? → candidate for `references/`
+3. What templates or assets are used in output? → candidate for `assets/`
+
+Example analysis:
+- "Rotate a PDF" → rotating requires rewriting the same code → `scripts/rotate_pdf.py`
+- "Query BigQuery metrics" → need table schemas each time → `references/schema.md`
+- "Build a frontend app" → same boilerplate HTML/React → `assets/hello-world/`
+
+## Step 3: Study Existing Skills
 
 Before writing, study 1-2 existing skills that match the chosen tier. Look for skills in the target repository or plugin to understand local conventions.
 
 Read `${CLAUDE_SKILL_ROOT}/references/skill-patterns.md` for concrete examples of each tier.
 
 Also read `CLAUDE.md` (or `AGENTS.md`) at the repository root for repo-specific conventions that the skill should follow.
 
-## Step 3: Write the SKILL.md
+## Step 4: Write the SKILL.md
 
 Create `<skill-directory>/<name>/SKILL.md`.
 
@@ -64,11 +85,34 @@ description: <what it does>. Use when <trigger phrases>. <key capabilities>.
 
 **Required fields:**
 - `name` — must match the directory name exactly
-- `description` — up to 1024 chars; include trigger keywords that help agents match user intent
+- `description` — up to 1024 chars, no angle brackets (`<` or `>`); include trigger keywords that help agents match user intent
 
 **Optional fields:**
 - `allowed-tools` — comma-separated list (e.g., `Read, Grep, Glob, Bash`); omit to allow all tools
 - `license` — license name or path (add when vendoring external content)
+- `metadata` — arbitrary key-value mapping for additional metadata
+- `compatibility` — environment requirements (max 500 chars); most skills don't need this
+
+For Claude Code-specific fields (`argument-hint`, `disable-model-invocation`, `context`, etc.), read `${CLAUDE_SKILL_ROOT}/references/claude-code-extensions.md`.
+
+### Description Guidelines
+
+The description is the **primary trigger mechanism** — it determines when agents activate the skill. All "when to use" information belongs here, not in the body.
+
+**Write in third person:**
+- Good: "Processes Excel files and generates reports. Use when..."
+- Bad: "I can help you process Excel files" or "You can use this to..."
+
+**Include natural trigger phrases:**
+```yaml
+# Good — specific triggers users would actually say
+description: Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for security issues", "audit security".
+
+# Bad — too vague, no trigger phrases
+description: A helpful skill for code quality.
+```
+
+**Pattern:** `<What it does>. Use when <trigger phrases>. <Key capabilities>.`
 
 ### Body Guidelines
 
@@ -87,11 +131,17 @@ Write the body in **imperative voice** — these are instructions, not documenta
 4. Include concrete examples of expected output
 5. End with validation criteria or exit conditions
 
+For workflow and output patterns, read:
+- `${CLAUDE_SKILL_ROOT}/references/workflow-patterns.md` — sequential workflows, feedback loops, plan-validate-execute
+- `${CLAUDE_SKILL_ROOT}/references/output-patterns.md` — template, examples, and structured data patterns
+
 **Size limits:**
-- Keep SKILL.md under **500 lines**
+- Keep SKILL.md under **500 lines** (< 5000 tokens recommended)
 - If approaching the limit, move reference material to `references/` files
 - Load reference files conditionally based on context (not all at once)
 
+**Use consistent terminology** — pick one term for each concept and stick with it throughout. Don't alternate between "API endpoint", "URL", "route", and "path".
+
 ### Attribution
 
 If the skill is based on or adapted from external sources, add an HTML comment **after** the frontmatter closing `---`:
@@ -108,7 +158,18 @@ https://github.com/example/original-source
 -->
 ```
 
-## Step 4: Create Supporting Files
+## Step 5: Create Supporting Files
+
+### What to Include
+
+Only include files that directly support the skill's function.
+
+### What NOT to Include
+
+Do not create extraneous documentation or auxiliary files:
+- README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md
+
+A skill should contain only what an agent needs to do the job. Not setup procedures, not user-facing docs, not development history.
 
 ### References (`references/`)
 
@@ -127,7 +188,12 @@ Reference from SKILL.md with:
 Read `${CLAUDE_SKILL_ROOT}/references/topic-a.md` for details on [topic].
 ```
 
-Keep each reference file focused on one topic. Use markdown with tables and code blocks.
+Guidelines:
+- Keep each reference file focused on one topic
+- Keep references **one level deep** from SKILL.md (no nested reference chains)
+- For files over 100 lines, add a table of contents at the top
+- For files over 10k words, include grep search patterns in SKILL.md
+- Information should live in either SKILL.md or references, not both
 
 ### Scripts (`scripts/`)
 
@@ -154,16 +220,32 @@ Use for workflow automation that benefits from structured Python.
 - Output structured JSON for agent consumption
 - Run from the **repository root**, not the skill directory
 - Document the script's interface in SKILL.md (arguments, output format)
+- Handle errors explicitly — don't punt to the agent
 
 ### Assets (`assets/`)
 
-Use for static files the skill references (templates, configs, etc.).
+Use for static files used in the skill's output (templates, images, boilerplate code, fonts). These are not loaded into context — they're copied or used directly.
 
 ### LICENSE
 
 Include a LICENSE file in the skill directory when vendoring content with specific licensing requirements.
 
-## Step 5: Register the Skill
+## Step 6: Validate the Skill
+
+Run the validation script to catch issues early:
+
+```bash
+uv run ${CLAUDE_SKILL_ROOT}/scripts/quick_validate.py <path/to/skill-directory>
+```
+
+The script checks frontmatter format, required fields, naming rules, and common mistakes. Fix any errors and re-run until validation passes.
+
+Alternatively, use the upstream validation tool:
+```bash
+skills-ref validate <path/to/skill-directory>
+```
+
+## Step 7: Register the Skill
 
 Registration steps vary by repository. Check the repository's `CLAUDE.md` or `README.md` for specific instructions.
 
@@ -172,22 +254,26 @@ Registration steps vary by repository. Check the repository's `CLAUDE.md` or `RE
 3. **Update permissions** — if the repo has `.claude/settings.json`, add `Skill(<plugin>:<name>)` to the `permissions.allow` array
 4. **Check CLAUDE.md** — read the repository's `CLAUDE.md` for any additional registration steps specific to that project
 
-## Step 6: Verify
+## Step 8: Verify
 
 Run through this checklist before finishing:
 
 ### Frontmatter
 - [ ] `name` matches directory name
-- [ ] `description` is under 1024 characters
-- [ ] `description` includes trigger keywords
+- [ ] `name` uses only lowercase letters, digits, hyphens (no leading/trailing/consecutive hyphens)
+- [ ] `description` is under 1024 characters, no angle brackets
+- [ ] `description` is in third person and includes trigger keywords
+- [ ] All "when to use" info is in description, not in body
 - [ ] No content before the opening `---`
 
 ### Content
 - [ ] SKILL.md is under 500 lines
 - [ ] Written in imperative voice
 - [ ] Steps are numbered and clear
 - [ ] Examples of expected output included
+- [ ] Consistent terminology throughout
 - [ ] Reference files loaded conditionally (not unconditionally)
+- [ ] No extraneous files (README.md, CHANGELOG.md, etc.)
 
 ### Registration
 - [ ] Directory name matches frontmatter `name`
@@ -199,6 +285,11 @@ Run through this checklist before finishing:
 - [ ] Uses `uv run ${CLAUDE_SKILL_ROOT}/scripts/...`
 - [ ] Has PEP 723 inline metadata
 - [ ] Outputs structured JSON
+- [ ] Handles errors explicitly
 - [ ] Documented in SKILL.md
 
+### Validation
+- [ ] `uv run ${CLAUDE_SKILL_ROOT}/scripts/quick_validate.py` passes
+- [ ] Tested with a real usage scenario
+
 Report any issues found and fix them before completing.