What is the core idea of writing-skills?

Writing-skills apply test-driven development to process documentation: you run failing tests (baselines) before writing the skill, then document the skill, verify the tests pass with the skill, and refactor to close loopholes.

How should the Skill frontmatter be structured?

Frontmatter must include only name and description, with the name using letters, numbers, and hyphens, and the description starting with 'Use when...'. Secondary guidance specifies max 1024 characters total.

When should I use writing-skills?

Use writing-skills when creating new skills, editing existing skills, or verifying that skills work before deployment, following the RED-GREEN-REFACTOR process to ensure reliability.

writing-skills

Scanned

npx machina-cli add skill parthalon025/autonomous-coding-toolkit/writing-skills --openclaw

Files (1)

SKILL.md

2.6 KB

Writing Skills

Overview

Writing skills IS Test-Driven Development applied to process documentation.

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides Skills are NOT: Narratives about how you solved a problem once

SKILL.md Structure

Frontmatter (YAML):

Only two fields supported: name and description
Max 1024 characters total
name: Use letters, numbers, and hyphens only
description: Third-person, describes ONLY when to use (NOT what it does)

---
name: Skill-Name-With-Hyphens
description: Use when [specific triggering conditions and symptoms]
---

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
Bullet list with SYMPTOMS and use cases

## Core Pattern
Before/after code comparison

## Quick Reference
Table or bullets for scanning

## Common Mistakes
What goes wrong + fixes

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

Write skill before testing? Delete it. Start over.

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior.

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Run same scenarios WITH skill.

REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Skill Creation Checklist

RED Phase:

Create pressure scenarios
Run scenarios WITHOUT skill - document baseline
Identify patterns in rationalizations/failures

GREEN Phase:

Name uses only letters, numbers, hyphens
YAML frontmatter with only name and description
Description starts with "Use when..."
Address specific baseline failures
Run scenarios WITH skill - verify compliance

REFACTOR Phase:

Identify NEW rationalizations from testing
Add explicit counters
Build rationalization table
Re-test until bulletproof

Source

git clone https://github.com/parthalon025/autonomous-coding-toolkit/blob/main/skills/writing-skills/SKILL.mdView on GitHub

Overview

Writing skills apply test-driven development to process documentation. You create pressure-test scenarios with subagents, observe baseline failures, document the skill, verify the skill makes tests pass, and refactor to close loopholes. The core principle is that you must witness failures without the skill to ensure the skill teaches the right behavior.

How This Skill Works

Follow RED-GREEN-REFACTOR: 1) Run pressure scenarios without the skill to establish a failing baseline. 2) Write the minimal skill documentation that addresses those failures and run the scenarios with the skill. 3) Refactor to close new rationalizations and re-test until the skill is bulletproof.

When to Use It

Create a new skill and establish baseline failures with pressure scenarios.
Edit an existing skill to counter newly discovered rationalizations and failures.
Verify that a skill prevents regression by re-running failing tests after changes.
Prepare for deployment with explicit documentation and countermeasures.
Iteratively refine the skill through red-green-refactor cycles to close loopholes.

Quick Start

Step 1: RED Phase — Run pressure scenarios WITHOUT the skill to establish a baseline.
Step 2: GREEN Phase — Write the minimal skill addressing the baseline failures and run the scenarios WITH the skill.
Step 3: REFACTOR Phase — Add explicit counters, build a rationalization table, and re-test until bulletproof.

Best Practices

Start with a failing baseline before writing the skill.
Keep YAML frontmatter limited to name and description, per the Skill structure.
Address specific baseline failures with explicit counters and rationalizations.
Run scenarios both without and with the skill to prove compliance.
Refactor to close loopholes and re-test until the skill is bulletproof.

Example Use Cases

Example 1: RED phase — run a pressure scenario with subagents and log the exact baseline failure without the skill.
Example 2: GREEN phase — write a minimal skill that directly addresses that failure and validate with the same scenarios.
Example 3: REFACTOR phase — add explicit counters for new rationalizations discovered during testing and update the rationalization table.
Example 4: Verification — re-run all scenarios WITH the skill to confirm compliance and updated behavior.
Example 5: Deployment prep — ensure frontmatter, guidelines, and countermeasures are documented before release.

Frequently Asked Questions

Add this skill to your agents