Lab · Beginner · 60 min
One SKILL.md That Triggers in Claude Code and Cursor
Write a release-notes skill with a script and a reference file, install it in two tools from one source, and tune the description until it triggers reliably.
Claude Code · Cursor · OpenAI Codex
Show all 4 stepsHide list
Step 1 of 4
Lab brief
Goal
A skill directory that activates on 'write release notes' prompts in both tools and stays quiet on unrelated prompts.
Failure mode
The skill never activates because the description says 'Helps with docs', or it activates on every writing task and hijacks unrelated work.
Staff move
Write the description as a routing rule (what + when + user phrases), keep the body short, and push deterministic steps into a script.
Step 2 of 4
1. Build the skill
--- name: release-notes description: Generate release notes from merged PRs and conventional commits since the last tag. Use when the user asks for release notes, a changelog, or "what shipped" for a version. --- # Release notes 1. Run scripts/collect.sh to list commits since the last tag. 2. Group by type (feat, fix, perf, docs). Skip chore/ci. 3. Follow references/style.md for tone and format. 4. Output Markdown under "## vX.Y.Z".
- scripts/collect.sh: git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:'%s (%h)'
- references/style.md: 10 lines of tone rules and one example entry
Step 3 of 4
2. Install from one source
- Keep the canonical copy in .agents/skills/release-notes (read by Codex)
- Symlink or sync it into .claude/skills/ and .cursor/skills/
- Confirm each tool lists the skill (e.g. /skills in Codex, skill picker in Cursor, /release-notes in Claude Code)
Step 4 of 4
3. Verify triggering
| Prompt | Should trigger? |
|---|---|
| Write release notes for v2.3 | Yes |
| What shipped since last tag? | Yes |
| Write a README section on setup | No |
| Summarize this PR | No |
Run each prompt 3 times per tool in a fresh session. Adjust the description until the table matches, then commit the skill with the test table in the PR description.