mirror of
https://github.com/getsentry/skills.git
synced 2026-09-14 20:00:03 +08:00
David Cramer
5cfc9e22a9
Add a root-level SPEC.md convention for skills and reverse engineer the canonical skill-writer spec as the reference implementation. This updates skill-writer so future skill changes separate runtime instructions from maintenance context: SKILL.md stays focused on activation and workflow, while SPEC.md captures intent, scope, source/evidence models, evaluation expectations, known limitations, and maintenance rules. It also adds focused guidance for reference architecture, source discovery, and persistent iteration evidence. The validator now checks SPEC.md structure when present and warns on long reference files instead of enforcing fixed integration reference filenames. That keeps coverage requirements while allowing skill-specific reference names. Validation: uv run skills/skill-writer/scripts/quick_validate.py skills/skill-writer --skill-class skill-authoring --strict-depth Co-authored-by: Codex <codex@openai.com>
44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
# Agent Instructions
|
|
|
|
## Skill Structure
|
|
```
|
|
skills/<skill-name>/SKILL.md
|
|
skills/<skill-name>/SPEC.md
|
|
```
|
|
|
|
If you use Claude marketplace sparse checkouts for this repo, include `skills` and `agents` alongside `.claude-plugin` because the root plugin manifest loads repo-root `skills/` and `agents/`.
|
|
|
|
## Creating/Updating Skills
|
|
ALWAYS use `/skill-writer` — it handles requirements, writing, registration, and validation.
|
|
|
|
- Do **not** create per-skill alias or symlink skills
|
|
- The repo-level `.agents/skills` path is a convenience mirror of canonical `skills/`
|
|
- List only canonical skills in public skill inventories (for example `pr-writer`, `skill-writer`)
|
|
|
|
### Registration Checklist
|
|
1. Create `skills/<skill-name>/SKILL.md`
|
|
2. Create `skills/<skill-name>/SPEC.md`
|
|
3. Add to `README.md` Available Skills table (alphabetical by canonical skill name; exclude aliases/symlinks)
|
|
4. Add to `.claude/settings.json`: `Skill(sentry-skills:<skill-name>)`
|
|
5. Add to allowlist in `skills/claude-settings-audit/SKILL.md`
|
|
|
|
## Key Conventions
|
|
- Frontmatter `---` must be the **first line** of SKILL.md — no comments before it
|
|
- `name` field must match the directory name exactly
|
|
- `description` includes trigger keywords — this is how agents discover the skill
|
|
- Attribution comments go **after** the closing `---`
|
|
- Python scripts: always use `uv run <script>`, never `python` or `python3`
|
|
- Keep SKILL.md under 500 lines; move reference material to `references/`
|
|
- Keep runtime instructions in `SKILL.md`; put intent, source/evidence model, evaluation, limitations, and maintenance rules in `SPEC.md`
|
|
|
|
## Commit Attribution
|
|
AI commits MUST include:
|
|
```
|
|
Co-Authored-By: (the agent's name and attribution byline)
|
|
```
|
|
|
|
## References
|
|
- Skill template and optional fields: `README.md`
|
|
- Testing and PR workflow: `CONTRIBUTING.md`
|
|
- [Agent Skills Spec](https://agentskills.io/specification)
|