Overview

Refactor a skill. A skill spends two budgets. Its description is loaded into every session, so each word there must do triggering work. Its body enters the context on invocation and stays there for the rest of the session, so each line there must be a step the agent performs or reference every path through the skill needs. Everything else moves behind a pointer or out of the skill.

Instructions

1. Pick the target. If the invocation names one, resolve it to its SKILL.md. Otherwise ask which skill. Read SKILL.md and every sibling file in its directory. If the invocation also names a change to make, that change sets the scope: the verdicts below cover the lines it adds or touches, the rest of the skill stays as it is, and anything noticed there is a follow-up.

2. Fetch the yardsticks. Fetch these pages. They calibrate the delete, demote, and rewrite verdicts below:

   • https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices
   • https://code.claude.com/docs/en/skills#frontmatter-reference and https://code.claude.com/docs/en/skills#skill-content-lifecycle
   • https://raw.githubusercontent.com/mattpocock/skills/main/skills/productivity/writing-for-agents/SKILL.md
   • https://raw.githubusercontent.com/mattpocock/skills/main/skills/productivity/writing-for-agents/SKILL-MECHANICS.md
   • The page for the model the skill targets: its model: frontmatter when set, otherwise the most capable model:
     • No model: or Fable 5.1: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1
     • opus: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5
     • sonnet: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5
     • haiku: no page of its own, use https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices