writing-skills

Create and test agent skills using TDD-style pressure scenarios with subagents.

Updated Jul 29, 2026
One-click install
npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill writing-skills-maicongambini
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/MaiconGambini/opencode-harness-guide/tree/main/skills/writing-skills
Command: npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill writing-skills-maicongambini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Untested skill documentation often fails in practice because agents rationalize around rules under time, sunk-cost, or authority pressure, and authors cannot know whether a skill teaches the right behavior without watching agents fail without it first. ## Core Features & Use Cases - TDD-based skill authoring: Applies the RED-GREEN-REFACTOR cycle to documentation by running baseline pressure scenarios with subagents, writing the skill to address observed failures, then closing loopholes. - Discovery optimization (CSO): Provides rules for writing trigger-focused descriptions, keyword coverage, naming conventions, and token-efficient skill structure. - Bulletproofing guidance: Includes rationalization tables, red-flag lists, and persuasion-principle research to make discipline-enforcing skills resistant to workarounds. - Use Case: Before deploying a new TDD-enforcement skill, run a scenario where an agent has 200 lines of untested code and a dinner deadline, document its excuses verbatim, then write the skill to counter exactly those rationalizations. ## Quick Start Ask the agent to create a new skill for a recurring technique, starting with baseline pressure scenarios before writing any documentation.

Frequently Asked Questions about writing-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test a skill before deploying it?

Run pressure scenarios with subagents without the skill first to capture baseline failures verbatim, then write the skill addressing those failures and re-test until agents comply. Combine three or more pressures like time, sunk cost, and authority for realistic results.

What makes a good skill description for discovery?

Start with "Use when..." and describe only triggering conditions and symptoms, never the skill's workflow. Descriptions that summarize the process cause agents to follow the description instead of reading the full skill body.

How do I stop agents from rationalizing around skill rules?

Close every loophole explicitly with negations, build a rationalization table from observed excuses, add a red-flags list, and state that violating the letter violates the spirit. Re-test after each change until no new rationalizations appear.

When should I not create a skill?

Skip skills for one-off solutions, well-documented standard practices, project-specific conventions that belong in project config, and mechanical constraints that can be enforced with validation or automation instead of documentation.

Can I render flowcharts from a SKILL.md file?

Yes, the included render-graphs.js script extracts dot blocks from a skill's SKILL.md and renders them to SVG files using graphviz. It supports rendering each diagram separately or combining all into one SVG.