# writing-skills

> Use when creating, editing, evaluating, testing, or verifying ANY skill or skill-related file (SKILL.md, SKILL.scenarios.yml, skill resources, skill scripts, or skill assets). If you're asked to evaluate or test a skill's effectiveness, that's skill development work - use this skill.

- Author: Landon Schropp
- Repository: LandonSchropp/skills
- Version: 20260111220350
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/LandonSchropp/skills
- Web: https://mule.run/skillshub/@@LandonSchropp/skills~writing-skills:20260111220350

---

---
name: writing-skills
description: Use when creating, editing, evaluating, testing, or verifying ANY skill or skill-related file (SKILL.md, SKILL.scenarios.yml, skill resources, skill scripts, or skill assets). If you're asked to evaluate or test a skill's effectiveness, that's skill development work - use this skill.
---

This skill teaches you how to create effective skills that agents actually follow.

**IMPORTANT: Evaluating and testing skills IS skill development work.** If you're asked to evaluate, test, or verify a skill's effectiveness, you're doing skill development and must follow this skill's workflow.

## Test-Driven Development

**Creating skills IS Test-Driven Development for process documentation.**

1. **Red:** Test scenarios with naive subagents, document how they fail without the skill
2. **Green:** Write the skill addressing those specific failures, verify agents now comply
3. **Refactor:** Close loopholes as you discover new rationalizations

**THE IRON LAW: NO SKILL WITHOUT A FAILING TEST FIRST.** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. This applies to NEW skills AND EDITS to existing skills.

- Did you write the skill before testing it? Delete it. Start over.
- Did you edit the skill without testing it? Delete it. Start over.

**No exceptions:**

- Not for "simple additions"
- Not for "just adding a section"
- Not for "documentation updates"
- Don't keep untested changes as "reference"
- Don't "adapt" while running tests
- Delete means delete

## Required Reading

**STOP. Read these documents NOW. Not later. Not "as you go." Right now.**

You MUST read/fetch ALL of these documents and follow their instructions before proceeding:

- See [Format Guide](references/format-guide.md)
- See [Evaluating Skills](references/evaluating-skills.md)
- See [Getting Agents to Follow Instructions](references/getting-agents-to-follow-instructions.md)
- [Skill Specification](https://raw.githubusercontent.com/agentskills/agentskills/main/docs/specification.mdx)
- [Skill Authoring Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices.md)
- [Persuasion Principles](https://raw.githubusercontent.com/obra/superpowers/main/skills/writing-skills/persuasion-principles.md)

**No exceptions:**

- Not "I'll read them as I need them"
- Not "I already understand the concepts"
- Not "I'll skim the overview section"
- Not "I'll come back to these later"
- Read means read. Fetch means fetch. Do it now.

## Skill Types

- **Discipline:** Rules and requirements agents must follow (e.g., `test-driven-development`, `verifying-before-completion`)
- **Technique:** Concrete methodology with steps to follow (e.g., `condition-based-waiting`, `root-cause-tracing`)
- **Pattern:** Way of thinking about problems (e.g., `flatten-with-flags`, `test-invariants`)
- **Reference:** API docs, syntax guides, tool documentation

## Creating Skill Files

Run `scripts/generate-template.ts <skill-directory>` to create both `SKILL.md` and `SKILL.scenarios.yml` with proper structure. The `<skill-directory>` is the path to the specific skill's directory (e.g., `skills/writing-skills`), not the directory containing the plugin or the directory containing all of the skills.

## Skill Creation Checklist (TDD Adapted)

**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**

- [ ] Red: Create test scenarios following references/evaluating-skills.md.
- [ ] Red: Run the scenarios WITHOUT skill. Document the baseline behavior before the skill is added.
- [ ] Red: Identify patterns in rationalizations/failures.
- [ ] Green: Run `scripts/generate-template.ts <skill-directory>` to create skill files.
- [ ] Green: Fill in `SKILL.scenarios.yml` with test scenarios identified from the Red phase.
- [ ] Green: Write `SKILL.md` following the generated template and references/format-guide.md.
- [ ] Green: Address the specific baseline failures identified in Red phase.
- [ ] Green: Include one excellent example.
- [ ] Green: Run the test scenarios WITH the skill. Verify agents now comply.
- [ ] Refactor: Identify NEW rationalizations from testing.
- [ ] Refactor: Add explicit counters following references/getting-agents-to-follow-instructions.md.
- [ ] Refactor: Build rationalization table from all test iterations.
- [ ] Refactor: Re-test and iterate until bulletproof.