Writing Skills

What it does

The Superpowers writing-skills source treats process documentation as behavior that should be tested. An author first creates a realistic scenario and observes an agent fail without the proposed guidance. The minimum useful skill is then written, the scenario is rerun and loopholes are refined. This discourages long instructions built around imagined problems or a single successful anecdote. The source distinguishes reusable techniques from a narrative of one past task and includes supporting material on discoverability, authoring and adversarial pressure testing. The outcome is a focused instruction package with evidence about tested behavior, not universal compliance.

When to use it

• Create a verification skill after observing agents claim completion without running the relevant command.
• Refine a review workflow that agents skip when a task appears urgent.
• Improve skill discovery text when a useful workflow is not selected for the situations it should cover.

Step-by-step workflow

1. Define a reproducible scenario with an observable expected behavior and run a baseline without the new skill.
2. Record the actual failure and the rationale the agent used, rather than inventing a hypothetical weakness.
3. Write the smallest reusable guidance addressing that failure, with clear discovery language and necessary references.
4. Rerun the scenario with the skill, then add realistic pressure cases that might bypass its rule.
5. Refactor ambiguous wording, rerun the checks and preserve the evidence and relevant supporting files before adoption.

Example request

Use writing-skills to develop a release-verification guide. Baseline: an agent receives a green build log but no proof of the deployed URL. Observe what it claims before writing instructions. The expected behavior is to verify the actual public artifact and report access failures honestly. Add a time-pressure scenario and a stale-log scenario. Do not equate one compliant run with proof that every future agent will comply.

Worked example

The baseline agent sees a successful upload and says the release is live. A narrow instruction can require a live URL check tied to the expected version, but the next scenario supplies yesterday’s cached page. That reveals a missing identity check. The author strengthens the guidance to compare the expected artifact and reruns both cases. Another test makes the URL inaccessible; a correct outcome reports the block instead of manufacturing success. These observations justify specific wording without turning the guide into an ever-growing list of unrelated commands.

What you get

A reusable SKILL.md with relevant references and a record of baseline failures, improved behavior and remaining limits.

How to evaluate the result

• The baseline demonstrates the targeted failure before the new rule is written.
• Evaluation checks observed actions and artifacts rather than agreeable prose.
• The final guide remains reusable and includes only necessary supporting material.

What you need

Understanding of test-first development, a host able to run isolated behavioral scenarios and representative tasks with observable outcomes. Authoring does not itself authorize installing or enabling the result.

Setup and activation

Read the Superpowers README for the selected client and retain the referenced templates and supporting files. This directory reviewed source only; it did not install or execute the skill. Before adopting it, scan the exact version, inspect requested tools and permissions, and test on disposable non-sensitive inputs. A compatible instruction format does not establish identical host capabilities.

Limits and considerations

Agent behavior varies across models, context and tools; a passing sample is not a universal guarantee. Pressure tests must use controlled resources. Review security and permissions separately before installation, especially if companion scripts are added.

Related workflows

• Use test-driven-development to understand the red/green/refactor reasoning behind the method.
• Use a separate exact-source security scan and host-specific installation review before enabling a new skill.

License and reuse

MIT at repository level. Preserve copyright and license notices; check companion files and external dependencies for their own terms.

Further reading

• Publisher setup and compatibility instructions
• Reviewed source at immutable commit