Guide · Agent skill
How to use the writing-skills agent skill: a step-by-step guide
Updated · written with AI from the project's own documentation and checked against our catalogue data
The writing-skills skill is a method for authoring agent skills, not a tool that runs your tasks. Once it is installed, the agent follows a structured process for creating, editing and checking skills before they are deployed. This guide explains what it does, how to install it, how to trigger it, and what to watch for, so you can use it to build and maintain your own skills.
Writing Skills Guideobra/superpowers · MIT Download the skill Quick start
- 1Download the ZIP. Download the writing-skills ZIP from the skill's page on this directory.
- 2Unzip into the skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 3Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Ask for skill authoring help. Describe a new or edited skill, or ask for a check that a skill works, in plain language.
- 5Run a baseline scenario. Before writing or changing a skill, run the scenario without it and note how the agent fails.
- 6Write and re-test the skill. Write the skill document to address those failures, then confirm the agent complies and close any loopholes.
- 7Render flowcharts if needed. If you have Graphviz and Node.js installed, run node render-graphs.js to turn a skill's flowcharts into SVG files.
What the writing-skills skill makes the agent do
The skill treats each new or edited skill like test-driven development. The agent first runs a baseline scenario without the skill to see how it fails, then writes the skill document, then checks that the agent complies and closes any loopholes it finds.
It also gives guidance on skill structure, on writing descriptions that trigger correctly, on when to split content into separate reference files, and on when to add flowcharts.
- Baseline first: run a pressure scenario without the skill and record the exact rationalizations the agent uses.
- Write the skill: address those specific violations with the skill document (SKILL.md).
- Verify and refactor: confirm the agent now complies, then find and plug new loopholes.
Install the writing-skills skill
Download the ZIP from the skill's page on this directory and unzip it into your personal skills folder, ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill to apply only to that project.
If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload
How to trigger the skill with natural requests
The skill's description says it applies when you are creating new skills, editing existing skills, or verifying that skills work before deployment. You do not need a special command; ask in plain language that matches one of those situations.
Name the skill's job clearly, including the skill name where it helps, so the agent knows you mean authoring rather than using a skill.
- "Help me write a new skill that enforces our code review checklist."
- "Edit my existing writing-skills-style skill so its description triggers more reliably."
- "Check whether this skill works before we share it with the team."
- "Review whether this skill description triggers reliably."
What the skill needs to run
The skill itself needs no network access. It does run scripts. The bundled render-graphs.js script needs Node.js to run. Graphviz, which provides the dot command, is needed only if you want to render diagrams from a skill's flowcharts.
The skill's reference files cover topics such as skill authoring best practices, bulletproofing against rationalization, flowcharts, discovery and descriptions, persuasion principles, and testing skills with subagents.
- Node.js: required to run render-graphs.js
- Graphviz (the dot command): required only when rendering flowcharts
- Network access: not used by this skill
node render-graphs.jsSafety notes on scripts and the network
This skill includes a script and so runs code on your machine. Read render-graphs.js before running it, as you would any script from a third party.
The skill does not use the network, according to its listing. The method also relies on running subagent scenarios manually, so the skill does not run tests on its own.
- Review render-graphs.js before running it.
- Expect to run subagent test scenarios yourself or ask the agent to do so.
- Graphviz must be installed separately if you render diagrams.
Tips for getting good results
Keep the skill's description to triggering conditions. The skill's own guidance is that a description should say when to use the skill, not summarise its workflow, because an agent that reads a workflow summary may follow the summary instead of the full skill.
Do not turn a simple one-off instruction into a skill. The skill itself says project-specific conventions belong in your project's instructions file.
- Start with a baseline: run the scenario without the skill before you write it.
- Write descriptions that begin with "Use when..." and describe triggers and symptoms.
- Use a separate reference file only for heavy material, such as reference content of around 100 lines or more.
- Add a flowchart only when it earns its place, and read the flowchart guidance first.
What people use it for
- Writing a new team skill that captures a proven technique and checking that agents follow it under pressure.
- Editing an existing skill and re-testing it so the change does not break compliance.
- Reviewing a skill description to see whether it triggers reliably on the requests you expect.
- Splitting a long skill into a SKILL.md plus reference files when the reference material is too large to keep inline.
- Rendering a skill's flowcharts into SVG files for documentation.
Frequently asked questions
Is the writing-skills skill free to use?
The skill is published under the MIT licence, as listed on its page. Check the licence file in the source repository for the full terms before you redistribute it.
What do I need to install writing-skills?
Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. You can also upload it under Settings → Capabilities → Skills in the Claude apps.
Do I need Node.js and Graphviz?
Node.js is needed to run the render-graphs.js script. Graphviz, which provides the dot command, is needed only if you render flowcharts to diagrams.
Does writing-skills run tests automatically?
No. The testing method relies on you or the agent running subagent scenarios manually, so you should plan to carry out those checks yourself.
Is this skill for using existing skills?
No. It is for authoring and maintaining skills. If you only want to use skills that already exist, you do not need it.
How does this compare with just writing instructions in a project file?
The skill itself says that simple one-off instructions belong in a project's instructions file, not in a skill. Use this skill when a technique is reusable across projects and worth testing before you share it.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you build or maintain your own agent skills and want a repeatable, test-first method for writing and checking them. Skip it if you only need to use existing skills or want a single project instruction, since the skill itself says those belong elsewhere. Expect to run the subagent test scenarios yourself, because the skill does not run tests automatically.
Download the skill