Review: obra/writing-skills on agentskill.sh

obra’s writing-skills skill teaches test-driven development applied to skill authoring. In practice, the skill asks authors to write baseline test cases before documenting techniques, observe failures without the skill in place, document the skill, verify compliance, and refactor to close loopholes. The framework is theoretically sound but faces a critical adoption barrier: it requires upfront discipline and has zero marketplace installs despite a 4.2/5 rating from five users.

Marketplace metrics paint a mixed picture. The skill has strong security (93/100), moderate content quality (67/100), and upstream GitHub stars (219,860 from the obra/writing-skills repo). However, the zero-install count is a red flag. A 4.2 rating from only five reviewers suggests the skill has seen limited exposure, not widespread validation at scale. Last updated June 2026, it is not stale, but the lack of momentum indicates adoption friction.

What writing-skills Actually Does

The skill positions itself as “Test-Driven Development applied to process documentation.” It maps TDD concepts directly onto skill creation: test cases become pressure scenarios with subagents; production code becomes the SKILL.md file; RED and GREEN phases map to agent baseline violations and compliance checks; refactoring involves closing loopholes.

The core principle is stark: “If you didn’t watch an agent fail without the skill, you don’t know if the skill teaches the right thing.” This forces authors into a RED-GREEN-REFACTOR loop before publishing. The skill assumes readers already understand TDD (the SKILL.md explicitly requires prior knowledge of a separate “superpowers:test-driven-development” skill) and provides three guidance documents bundled as supporting files.

The SKILL.md specifies when to create a skill (technique wasn’t obvious, you’d reference it again, pattern applies broadly) and when not to (one-off solutions, standard practices already well-documented, project-specific conventions). It defines three skill types: technique (concrete method with steps), pattern (way of thinking), and reference (API docs, syntax guides).

The most valuable section covers Claude Search Optimization (CSO). It warns against a specific failure mode: descriptions that summarize workflow cause Claude to read the description and skip the skill body. Testing allegedly revealed that a description saying “code review between tasks” made Claude perform one review instead of two, even though the skill’s flowchart showed two stages. Changing the description to just triggering conditions fixed the issue.

Installation and Platform Compatibility

Installation on Claude Code follows the standard path: skills live in ~/.claude/skills and are loaded at runtime. The skill targets Claude, Claude Code, and Codex platforms, covering a broad range of Anthropic’s agent surfaces.

The SKILL.md structure requirements are prescriptive. Frontmatter requires name and description fields only (per agentskills.io/specification), with a 1024-character limit and no special characters in the name. The description must start with “Use when…” to signal triggering conditions, avoiding workflow summaries. The skill provides templates for the body sections: Overview, When to Use, Core Pattern, Quick Reference, Implementation, Common Mistakes, and optional Real-World Impact.

However, the skill provides no automation or validation tooling. No CLI, no linter, no test harness is bundled. Users must manually set up subagents, run baseline scenarios, and submit feedback via POST requests to agentskill.sh (or use the CLI tool npx @agentskill.sh/cli feedback). This friction is non-trivial for teams unfamiliar with the TDD workflow.

Strengths and Weaknesses

Writing-skills excels at one specific task: teaching disciplined skill authoring to teams already committed to TDD. The CSO guidance is concrete and backed by testing data (the workflow-in-description trap). The SKILL.md template is well-structured and the distinction between skill types is clear.

The weakness is dependency chain. The skill requires prior mastery of test-driven development (referenced as a prerequisite), assumes readers understand how to set up subagents for pressure testing, and offers no quick-start path for teams new to the TDD mindset. The content quality score of 67/100 likely reflects this steep onboarding curve.

Zero installs are the loudest signal. A skill rated 4.2/5 in isolation looks credible, but only five users have rated it, and none report using it in production (or at least none have installed it via the marketplace). This could mean the skill is niche by design, but it also suggests the agentskill.sh marketplace itself has limited awareness or adoption.

Comparison to Alternatives

Approach	Overhead	Scope	Best For
writing-skills (TDD-based)	High (baseline testing, RED-GREEN cycles)	Reusable techniques across projects	Teams committed to rigor and repeatability
Anthropic official best practices	Low (read-only reference)	Official guidance on skill structure	Quick-turnaround, low-risk authoring
Project-specific CLAUDE.md	Low (inline in repo)	Project conventions only	Single project, team-local rules

For teams aiming to publish reusable, battle-tested skills, writing-skills offers structure. For one-off agent setup or tight deadlines, the official Anthropic best practices guidance (referenced in the skill’s supporting files) is faster and carries institutional authority.

Critical Details

The skill’s supporting files include anthropic-best-practices.md (unclear if this duplicates or complements the skill’s guidance), examples/CLAUDE_MD_TESTING.md, graphviz-conventions.dot, persuasion-principles.md, render-graphs.js, and testing-skills-with-subagents.md. This file list is diverse and suggests the skill has grown organically, but the AIgentic review payload does not include the content of these files, so their value cannot be assessed here.

The skill references the agentskills.io/specification document for all supported frontmatter fields. This is a good link, but the skill itself documents only two required fields (name and description), leaving room for confusion about optional fields.

Security score is strong (93/100), but this likely reflects the skill’s minimal runtime footprint (it is documentation, not executable code). Content quality (67/100) is the softer metric and suggests either sparse examples, unclear writing, or incomplete coverage. Given the skill’s prescriptive nature and prerequisite dependencies, unclear onboarding is the likely culprit.

When to Use (and When to Skip)

Use writing-skills if you are committing to a sustained skill authoring program, expect skills to be used across multiple projects, and have bandwidth for TDD discipline. The framework is strongest for teams building internal skill libraries that will be referenced and refined over time.

Skip writing-skills if you need to ship a single skill quickly, are authoring a project-specific convention (keep it in CLAUDE.md instead), or are uncomfortable with test-driven development. The skill’s prerequisite assumption around TDD means teams unfamiliar with RED-GREEN-REFACTOR will face friction.

The zero-install count suggests even the marketplace recognizes this as a niche tool. The 4.2 rating is respectable but not decisive when paired with minimal user feedback. The security score is reassuring, but the content quality score hints at onboarding friction that potential users would feel.

Takeaways

The writing-skills skill is well-intentioned and technically sound, but adoption friction and prerequisite dependencies limit its audience. The CSO guidance on description fields is valuable and specific, backed by testing data that improves the skill’s credibility. However, zero marketplace installs despite a 4.2 rating signal that even the skill’s target audience (TDD-committed teams) has not yet found it useful enough to adopt at scale. The five-user rating pool is too small to distinguish between genuine niche appeal and obscurity. Consider this skill if your team is already using test-driven development and expects to author multiple reusable skills; otherwise, rely on Anthropic’s official guidance or inline project documentation.

Further reading

• agentskill.sh marketplace entry for obra/writing-skills - The live skill listing and feedback interface.
• agentskills.io specification - Official schema for skill frontmatter and metadata.
• Anthropic’s official skill authoring guidance - Vendor-published best practices that complement or supersede TDD-based approaches.
• obra/writing-skills GitHub repository - Source code and issue tracker for the skill’s development.