writing-skills

Guides creation, testing, and optimization of agent skill units with templates and standards.

Updated Apr 4, 2026
One-click install
npx skills add https://github.com/SleyiW/iWana-neXt --skill writing-skills-sleyiw
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/SleyiW/iWana-neXt/tree/main/.agents/skills/writing-skills
Command: npx skills add https://github.com/SleyiW/iWana-neXt --skill writing-skills-sleyiw

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Agent skills often fail because descriptions don't trigger discovery, rules get rationalized away under pressure, and monolithic files waste context tokens. This Skill provides a decision-tree dispatcher with templates, standards, and testing methodology to create skills that agents actually find and follow. ## Core Features & Use Cases - Tiered Architecture Guidance: Routes you to Tier 1 (single-file), Tier 2 (multi-file with references), or Tier 3 (platform-scale) structures based on complexity. - Discovery Optimization (CSO): Teaches trigger-based descriptions, keyword strategy, and naming conventions so skills get selected from large libraries. - Anti-Rationalization & Testing: Provides RED-GREEN-REFACTOR pressure-testing methodology and persuasion principles to bulletproof discipline-enforcing rules. - Use Case: You wrote a TDD skill but agents keep skipping tests under deadline pressure. Use this Skill to run baseline pressure scenarios, capture rationalizations verbatim, and add explicit counters until compliance holds. ## Quick Start Ask the agent to help you create a new skill for a specific task, and it will walk you through template selection, description optimization, and testing.

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 skill description that agents actually trigger on?

Write descriptions starting with "Use when..." listing only trigger conditions, never workflow summaries. Include exact error messages, symptoms, and tool names as keywords, and keep the description in third person under 500 characters.

How to test an agent skill before deploying it?

Apply the RED-GREEN-REFACTOR cycle: run pressure scenarios without the skill to capture baseline failures verbatim, write the skill addressing those specific rationalizations, then re-test with combined pressures like time, sunk cost, and exhaustion until no new loopholes appear.

When should I split a SKILL.md into multiple reference files?

Split when SKILL.md exceeds roughly 200-500 lines or covers multiple related sub-topics. Keep references one level deep from SKILL.md, since agents may only partially read files reached through nested reference chains.

Why do agents ignore rules in discipline-enforcing skills?

Agents rationalize under pressure with excuses like "spirit not letter" or "I'll test after." Counter this with explicit loophole negations, a rationalization table, red-flag checklists, and strong ALWAYS/NEVER language backed by authority and commitment principles.

What naming conventions should agent skills follow?

Use gerund or verb-first lowercase hyphenated names like creating-skills or flatten-with-flags. The directory name must exactly match the name field in the YAML frontmatter, and the entry file must be named SKILL.md in all caps.