mirror of https://github.com/getsentry/skills.git synced 2026-09-14 20:00:03 +08:00

Files

T

David Cramer 5cfc9e22a9 feat(skill-writer): Add skill specs and evidence guidance (#128 )

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>

2026-04-26 10:24:30 -07:00

1.8 KiB

Raw Permalink Blame History

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

Create skills/<skill-name>/SKILL.md
Create skills/<skill-name>/SPEC.md
Add to README.md Available Skills table (alphabetical by canonical skill name; exclude aliases/symlinks)
Add to .claude/settings.json: Skill(sentry-skills:<skill-name>)
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

1.8 KiB Raw Permalink Blame History