AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

skill-writer

Create, synthesize, and iteratively improve agent skills following the Agent Skills specification. Use when asked to "create a skill", "write a skill", "synthesize sources into a skill", "improve a skill from positive/negative examples", "update a skill", or "maintain skill docs and registration". Handles source capture, precision passes, authoring, registration, and validation.

Original source
getsentry
License
Apache-2.0
Pinned revision
d12f250460ffd961f549dbebf7eeb0cf4afd4c2e

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read getsentry--skill-writer at revision d12f250460ffd961f549dbebf7eeb0cf4afd4c2e, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 41

references/design-principles.md

Skill Design Principles

Use this guide to keep skill instructions dense, scannable, and worth their token cost.

Core Rule

  • Every line should help the agent decide, do, or verify something.
  • Prefer tables, checklists, templates, and input/output examples over explanatory prose.
  • Keep rationale to one short sentence unless the agent is likely to make the wrong choice without it.

Precision Before Addition

Before adding instructions, choose one:

| Action | Use when | |--------|----------| | replace | an existing rule is vague, stale, or pointing at the wrong behavior | | narrow | the current rule is mostly right but over-triggers or invites extra work | | move | the content belongs in SOURCES.md, SPEC.md, or a routed reference | | delete | the content repeats another rule or no longer changes behavior | | add | no existing rule can cover the new behavior without becoming less precise |

Do not add a new section, reference, or checklist until replacement, narrowing, moving, and deletion have been considered.

Keep Vs Cut

| Keep | Cut | |------|-----| | project-specific conventions | generic background the agent already knows | | non-obvious gotchas | motivational filler | | exact commands, schemas, and templates | repeated restatements of the same rule | | branch logic and defaults | long essays where a table would work | | one strong example | multiple weak examples saying the same thing | | behavior-changing constraints | source notes that belong in SOURCES.md |

Match Structure To Fragility

| Fragility | Preferred structure | Avoid | |-----------|---------------------|-------| | high | exact steps, strict templates, validation gates | open-ended guidance | | medium | short checklist plus examples | long rationale-heavy prose | | low | brief goals and constraints | overspecified playbooks |

Preferred Instruction Shapes

| Need | Preferred shape | |------|-----------------| | choose a path | decision table | | do a repeatable task | numbered checklist | | enforce output structure | template or schema | | show style or tone | input/output examples | | diagnose failures | symptom/cause/fix matrix | | communicate exact facts | compact reference table |

Description Rules

  • Keep description in third person.
  • Put trigger language in description, not the body.
  • Front-load what the skill does and when to use it.
  • Do not spend description space on internals unless they improve triggering.

Runtime Writing Rules

  • Use imperative voice.
  • State one default path before mentioning alternatives.
  • Use one term per concept; do not rotate synonyms.
  • Put universal rules in SKILL.md; put optional depth in routed refs.
  • If a section is mostly explanation, cut it or replace it with a denser structure.

Reference Rules

  • Reference filenames should predict their contents.
  • Each reference should answer one lookup question.
  • Keep runtime references flat under references/.
  • For related variant-specific references, use sibling files with a shared prefix and explicit differentiator.
  • Every bundled reference should have a direct "open when..." entry in SKILL.md.
  • Do not create catch-all files for notes, context, or mixed patterns.

Independence And Portability

  • Do not require another skill by name at runtime.
  • Use skill-root-relative paths by default.
  • Reuse established repo-specific path variables only when the repo already standardizes on them.
  • Label provider-specific mechanics explicitly and add portability notes when they matter.

Long Files

  • Keep SKILL.md short enough to scan as a router.
  • For references over 100 lines, add ## Contents.
  • If a reference grows because it mixes multiple lookup needs, split it.