writing-skills

Create, evaluate, and refactor Claude skills using progressive disclosure and TDD-style testing.

1|Updated Sep 15, 2026
One-click install
npx skills add https://github.com/amoai-tech/mdeai --skill writing-skills-amoai-tech
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/amoai-tech/mdeai/tree/main/.claude/skills/writing-skills
Command: npx skills add https://github.com/amoai-tech/mdeai --skill writing-skills-amoai-tech

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Skills often fail because they trigger at the wrong time, overload context with duplicated reference material, or are never verified against real agent behavior. This Skill provides an authoring contract, quality gate, and testing methodology so skills trigger reliably, stay concise, and are validated against baselines before adoption. ## Core Features & Use Cases - Authoring contract and quality gate: Enforces discovery metadata rules (lowercase kebab-case name, 'Use when' descriptions), progressive disclosure structure, and link/ownership validation before a skill is considered ready. - TDD-style skill testing: Applies RED-GREEN-REFACTOR to skill development using pressure scenarios, verbatim rationalization capture, and loophole closing until agents comply under maximum pressure. - Reference library: Includes Anthropic best-practices digest, persuasion-principles research for compliance-critical skills, and a subagent pressure-testing guide. - Use Case: When a 900-line SKILL.md repeats three reference guides, use this Skill to move heavy material into references/, tighten the trigger description, and add eval prompts with baseline-vs-candidate evidence. ## Quick Start Use the writing-skills skill to review my new SKILL.md for trigger quality, context size, and missing evals.

Frequently Asked Questions about writing-skills

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

FAQPage Schema
How do I write a good SKILL.md description for discovery?

Write a description that starts with 'Use when' and contains only trigger conditions, never a summary of the workflow. Use a lowercase kebab-case name and include realistic trigger phrasings so the agent can discover the skill from natural user requests.

How do I test whether a Claude skill actually works?

Apply TDD to skill testing: run pressure scenarios without the skill to capture baseline failures (RED), write the skill to address those failures (GREEN), then close loopholes by documenting new rationalizations verbatim and adding explicit counters (REFACTOR). Store test prompts in evals/evals.json.

What is progressive disclosure in skill authoring?

Progressive disclosure keeps the main SKILL.md concise, preferably under 500 lines, while moving heavy reference material to references/, deterministic helpers to scripts/, and reusable templates to assets/. These resources load only when needed, controlling context cost.

When should I consolidate overlapping skills instead of creating a new one?

Prefer improving an existing canonical skill whenever a new skill would own the same workflow. Check overlap before authoring, make ownership versus neighboring skills explicit, and avoid duplicating shared standards inside individual skills.

Why does my skill fail under pressure even with clear rules?

Agents rationalize around rules using excuses like 'spirit not letter' or sunk-cost reasoning. Close each loophole with explicit negations, a rationalization table, red-flag lists, and updated trigger descriptions, then re-test until no new rationalizations appear.