Skip to content
SkillModel-led3,655 tokens in use

writing-skills

Applies TDD to skill authoring: baseline an agent without the skill, write the skill, then close loopholes until it complies.

322,762 stars on the repository MIT Licenseobra/superpowers · skills/writing-skills
/plugin install superpowers@claude-plugins-official
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing writing-skills costs

20tokens idle
3,655tokens in use
20,137tokens, up to

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Up to adds the files its instructions link. Counts are approximate, made offline with cl100k_base.

Model dependence Model-led

Script-ledMixedModel-led

Mostly instructions, so how well it works depends on the model that follows them.

This describes the skill's structure, how much of it is scripts. It does not say how well it works. Scripts: render-graphs.js.

Touches

shelldetectednetworkdetectedwrites filesdetected

Declared tags come from the skill's frontmatter; detected ones from its scripts, its code blocks and the commands it names in inline code. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Excellent
  • Frontmatter12/15
  • Structure25/25
  • Examples15/15
  • Output15/15
  • Size10/15
  • Resources9/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Good
  • Runs shell commands−5

    does this on the machine, and the frontmatter does not say so

    render-graphs.js, line 18
  • Reaches the network−10

    does this on the machine, and the frontmatter does not say so

    render-graphs.js, line 116
  • Writes files−8

    does this on the machine, and the frontmatter does not say so

    render-graphs.js, line 142

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Good
  • Development activity56
  • Maintenance68
  • Community64
  • Maturity36
  • Momentum40

Writing Skills treats creating or editing a skill as test-driven development for process documentation. You run a pressure scenario with subagents to see how the agent fails without the skill, write the skill to address those failures, verify the agent now complies, and refactor to close new loopholes. Guidance covers skill types, directory layout, descriptions, flowcharts and code examples.

What You Get

  • A mapping from TDD concepts to skill creation
  • Guidance on skill types and file organization
  • Rules for descriptions, keywords and naming in a discovery reference
  • Flowchart conventions with a Node script that renders the diagrams
  • Anthropic’s official skill authoring best practices as a reference

Common Use Cases

  • Creating a new skill for a repeated technique
  • Editing an existing skill and re-testing it
  • Testing a discipline skill under time and sunk-cost pressure

What Makes It Unique

It tests documentation the way code is tested: the baseline failure of an agent without the skill is the failing test. The skill spells out the rationalizations agents use and asks authors to add an explicit counter for each.

Under The Hood

Instructions with reference files and a render-graphs.js script. The script extracts the dot blocks from a skill’s SKILL.md, runs the local graphviz dot program on them and writes SVG files next to the skill, and it exits with install hints when graphviz is missing. The agent writes skill files to your skills directory, such as ~/.claude/skills, and dispatches subagents for pressure tests. One graphviz conventions file ships in a format the label could not read.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers