Writing Skills

If you're building skills for Claude, this is your meta-guide. It treats skill writing as test-driven development for documentation: run a baseline test with a subagent to watch it fail without the skill, write the skill to fix that specific behavior, then verify compliance. The core insight is about Claude Search Optimization, where descriptions must contain triggering conditions, not workflow summaries, because testing showed Claude will follow the description and skip reading the actual skill content. Includes concrete structure templates, naming conventions, and a detailed breakdown of what makes skills discoverable. Assumes you already understand TDD fundamentals from the aegis skill. Most useful when you're actually creating or debugging skills that Claude isn't finding or following correctly.

GitHub stars: 492
last updated: Jun 11, 2026

View on GitHub

Install

$ npx -y skills add ganyuanran/aegis --skill writing-skills --agent claude-code

Installs into .claude/skills of the current project.

Files

Writing Skills

Purpose

Create the smallest reusable skill that changes decisions or improves task execution without constraining unrelated work. Skill changes use behavior validation, not a code TDD route. This validation does not require loading aegis:test-driven-development.

Default Path

1. Establish Need And Ownership

Name the reusable behavior gap, intended users/hosts, and non-goals.
Check whether an existing skill, project rule, host adapter, or automated check already owns it. Prefer the smallest existing owner.
For an existing skill, inspect its references, manifests or generated copies, discovery tests, and bundled resources before changing or retiring them.
Create a skill only for reusable, non-obvious guidance. Keep one-off project conventions in the project owner and automate mechanical constraints when practical.