writing-skills

Create and test agent skills using a TDD-based RED-GREEN-REFACTOR documentation workflow.

Updated Jun 9, 2026
One-click install
npx skills add https://github.com/gyc-12/Archipelago --skill writing-skills-gyc-12
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/gyc-12/Archipelago/tree/main/modules/collaboration-runtime/src-tauri/experts/skills/writing-skills
Command: npx skills add https://github.com/gyc-12/Archipelago --skill writing-skills-gyc-12

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing effective agent skills is hard because untested documentation often fails under real-world pressure, and authors cannot know if a skill actually changes agent behavior without observing baseline failures first. ## Core Features & Use Cases - TDD-Based Skill Authoring: Applies the RED-GREEN-REFACTOR cycle to documentation by running baseline pressure scenarios with subagents before writing any skill content. - Rationalization Bulletproofing: Provides rationalization tables, red flag lists, and explicit loophole counters to make discipline-enforcing skills resistant to agent excuses. - Discovery Optimization (CSO): Defines rules for names, descriptions, keywords, and token efficiency so future agents can find and correctly trigger the skill. - Use Case: When creating a new skill like a code-review checklist, run pressure scenarios without it, document how agents rationalize skipping steps, then write the skill targeting those exact failures and re-test until compliant. ## Quick Start Ask the agent to create a new skill for a recurring technique, starting with baseline pressure-test scenarios before writing the SKILL.md file.

Frequently Asked Questions about writing-skills

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

FAQPage Schema
How do I create a new agent skill with SKILL.md?

Create a directory containing a SKILL.md file with YAML frontmatter defining name and description, followed by markdown instructions. This skill recommends testing baseline agent behavior with pressure scenarios first, then writing content that addresses observed failures.

How to test whether a skill actually changes agent behavior?

Run pressure scenarios with subagents without the skill to capture baseline failures verbatim, then re-run the same scenarios with the skill loaded. Combine three or more pressures like time, sunk cost, and authority to verify compliance under realistic stress.

What should go in a SKILL.md description field?

The description should start with "Use when..." and describe only triggering conditions and symptoms, never the skill's workflow. Write in third person, keep it under 500 characters, and include searchable keywords like error messages and symptoms.

Why do agents ignore skills under time pressure?

Agents rationalize skipping rules when facing sunk cost, deadlines, or authority pressure. The fix is bulletproofing: add explicit negations for each observed excuse, rationalization tables, red flag lists, and foundational principles like "violating the letter is violating the spirit."

When should I not create a skill?

Skip skill creation for one-off solutions, project-specific conventions better placed in CLAUDE.md, well-documented standard practices, and mechanical constraints that can be enforced with validation or automation instead of documentation.