Test-Driven Skill Authoring
Create, revise, and verify Agent Skills with a test-driven documentation workflow.
The skill is primarily documentation and testing guidance; it requests no credentials, sensitive data, or elevated permissions, and shows no malicious exfiltration or destructive default behavior. However, imperative language and the advice to delete prior code lack explicit user confirmation, rollback, and data-flow guidance, while publisher identity is unverified, so trust is materially reduced.
The RED-GREEN-REFACTOR process, scenario taxonomy, and failure-feedback guidance are reasonably structured. However, the supplied SKILL.md ends mid-deployment checklist, depends on test-driven-development, subagents, and external references not fully defined within this skill, and static evidence does not reproduce key paths, so points are deducted.
The audience and main scenarios—creating, editing, and verifying agent skills—are clear, and the document distinguishes discipline, technique, pattern, and reference skills. Trigger conditions remain broad, non-fit boundaries and input/output contracts are limited, Chinese-language use and mainland-China reachability are not addressed, and core testing depends on a specific agent runtime, so points are deducted.
The skill has strong information architecture, progressive-disclosure references, naming guidance, examples, anti-patterns, and repository-level MIT/version context. It lacks an explicit maintainer, changelog, stable version/update policy, and complete dependency-installation guidance within the skill; some external references are not independently verifiable from the supplied material, so points are deducted.
The document gives concrete pressure scenarios, failure categories, rationalization handling, and iteration guidance that could directly help skill authors. Static review cannot establish that agents actually follow the workflow, and the process depends on subagents, runtime skill directories, and a test harness; outputs still require human judgment, so the score remains below the static ceiling.
Committed testing-related scripts, scenario examples, and methodological references provide limited auditability. The supplied material lacks real execution results or a complete skill-specific test report, and claims about research and final compliance rates cannot be independently reproduced from these files, so the score remains conservative.
- This assessment is based only on the supplied source files; no scripts, tests, or subagent scenarios were executed.
- The supplied SKILL.md ends mid-deployment checklist, so the complete workflow, failure handling, and rollback requirements cannot be confirmed.
- Before use, verify availability of superpowers:test-driven-development, subagent capabilities, the runtime skills directory, and the evaluation harness; establish user confirmation and backup rules before deleting or rewriting existing content.
- The core documentation and examples target English and specific agent ecosystems, so Chinese teams may need localized triggers, examples, and environment guidance.
What does this skill do, and when should you use it?
This is a meta-skill in the Superpowers repository for creating, editing, and validating other skills before deployment. It applies the RED-GREEN-REFACTOR cycle from test-driven development to process documentation: observe failures without the skill, write the minimal guidance, then retest and close loopholes. It covers skill structure, discovery optimization, cross-references, examples, anti-patterns, and deployment checks. Users must understand superpowers:test-driven-development first.
It instructs an agent to create pressure scenarios executed by subagents, record baseline behavior without the target skill, and capture the rationalizations that caused violations. It guides authoring an SKILL.md with YAML name and description fields, searchable triggers, structured sections, examples, and appropriate file organization. It requires rerunning the scenarios with the skill loaded, identifying new loopholes, and iterating until behavior is compliant. It also recommends wc -w for word-count checks and the repository's render-graphs.js for rendering flowcharts when needed.
- A maintainer adding a reusable skill to Superpowers or another Agent Skills repository
- An author revising an existing skill whose rules may be bypassed under time or delivery pressure
- A team validating a skill's behavior before making it available to coding agents
- An author standardizing SKILL.md metadata, discovery terms, examples, and deployment checks
What are this skill's strengths and limitations?
- Defines a complete loop from baseline failure through verification and refinement
- Requires documenting actual agent rationalizations instead of relying only on editorial review
- Covers metadata, discovery, organization, anti-patterns, and deployment checks
- Applies to both new skills and edits to existing skills
- Requires background knowledge of superpowers:test-driven-development
- Pressure scenarios and micro-tests can be time-consuming and costly; the document describes full scenario runs as slow and expensive
- No standalone test command is provided for this skill; the README points to the superpowers-evals drill harness for skill behavior tests
- It is primarily procedural documentation, not an independent automation tool
How do you install this skill?
The repository bundles 14 skills, and the README documents installation for the full Superpowers collection rather than a standalone command for this skill. Place skills/writing-skills/ in the runtime's skills directory, whose exact location depends on the Agent harness. The README lists collection installation procedures for Claude Code, Codex App, Codex CLI, Cursor, OpenCode, Pi, and other supported environments.
How do you use this skill?
Use it when creating, editing, or verifying a skill, for example: "Create a new skill for handling database migrations and verify it before deployment." Run baseline pressure scenarios without the target skill, write or revise SKILL.md, then repeat the scenarios with the skill loaded and fix any rationalization loopholes. Understand superpowers:test-driven-development before applying this skill.
How does this skill compare with similar options?
The skill explicitly maps skill authoring to test-driven development: pressure scenarios are test cases, SKILL.md is production code, violations without the skill are RED, compliance with the skill is GREEN, and closing newly discovered rationalization loopholes is REFACTOR.