Skill-writing principles for Claude Code from 159 open-source skills

A developer has published 10 principles for writing effective skills for Claude Code, derived from building and maintaining an open-source skill registry with 159 skills. The principles focus on practical implementation patterns observed through actual agent usage.

Key skill-writing principles

• Don't state the obvious - Push Claude out of its defaults rather than reinforcing them
• Gotchas section - Considered the highest ROI content in any skill
• Skills are folders, not files - Use references/, scripts/, assets/ subdirectories
• Don't railroad - Provide guidelines instead of rigid step sequences
• First-time setup via config.json - Place configuration files directly in the skill folder
• Description field is a trigger condition - Not just a summary
• Give skills memory - Use logs, JSON, or SQLite between runs
• Ship scripts alongside prose - Example: fetch_events.py is more valuable than 200 lines of explanation
• On-demand hooks - Use /careful blocks to restrict destructive commands only when invoked
• Skills compose - Reference other skills by name; Claude will invoke them if installed

Implementation details

The principles come from the AbsolutelySkilled repository (github.com/AbsolutelySkilled/AbsolutelySkilled), which contains 159 open-source skills. All skills are installable via npx skills add. The developer emphasizes that these patterns emerged from watching how agents actually use the skills in practice, not from theoretical design.

For developers building skills for AI coding agents, these principles provide concrete guidance on structuring skills effectively. The focus on practical implementation—like using folders instead of single files and including actual scripts rather than just explanations—reflects real-world usage patterns.