Skip to content
Get packs

Writing Skills Guide

Guides the agent to create, edit and test new agent skills using a test-driven method

Source Download skill
Repository
jnMetaCode/superpowers-zh
Stars
8,444
Licence
MIT
Files
6 files

What it does

When you ask the agent to create or improve a skill (a reusable instruction file that teaches an AI agent a capability), this skill makes it follow a structured process: first observe the agent failing without the skill, then write the skill, then check it fixes that failure and close loopholes. It also gives rules for good skill descriptions, keeping documents short, naming, and when a skill should not be created at all. The included script can turn flowcharts in a skill into SVG images for review.

Great for

  • Developers and teams writing their own SKILL.md files for Claude Code or similar agents
  • People maintaining a shared library of agent skills who want consistent structure and trigger descriptions
  • Anyone who wants to check whether a skill actually changes agent behaviour before deploying it

Skip it if

  • Casual users who only want to use existing skills; this is a meta-guide for authoring them
  • Simple one-off instructions that belong in a project CLAUDE.md file, which the skill itself says should not become a skill
  • Teams expecting a fully automated testing tool; the testing method described relies on manually run subagent scenarios

Try asking

  • “Create a new skill that teaches the agent how to debug flaky tests, following the repo's conventions”
  • “Review my existing SKILL.md and tell me if its description summarises the workflow when it should only list trigger conditions”
  • “Help me test whether my skill actually changes the agent's behaviour using pressure scenarios before I publish it”
  • “Render the flowcharts in my skill to SVG so I can show my colleague the process”
Step-by-step guide: how to use Writing Skills GuideInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 6 original files, the MIT licence and an attribution note.

    writing-skills.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip writing-skills.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip writing-skills.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Write the skill description as trigger conditions only ("Use when..."), without summarising the steps, as the skill warns this makes agents skip the body
  • Run the agent on the task without the skill first and note the exact excuses it gives, then write the skill to counter those specific failures
  • Install render-graphs.js only after confirming Graphviz is present; it executes the local dot command on your files

What's inside

  • anthropic-best-practices.md
  • examples/CLAUDE_MD_TESTING.md
  • persuasion-principles.md
  • render-graphs.js
  • SKILL.md
  • testing-skills-with-subagents.md

Redistributed unmodified from jnMetaCode/superpowers-zh under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.