Creating Skills

Contents

• Overview
• When to Use
• The Process
  • Mode A: Create New Skill
  • Mode B: Modify Existing Skill
  • Mode C: Validate Skill
• Rules
  • name
  • description
  • Optional Fields
  • Structure
  • Progressive Disclosure
  • Directory Structure
  • Script Design
  • Content Principles
  • Multilingual
  • Static Analysis
• Tips

Overview

Creates and maintains Claude Code skills. Supports three modes: create, modify, validate.

When to Use

• Creating a new skill from scratch
• Modifying or improving an existing skill
• Validating a skill before deployment
• Fixing validation errors or warnings

The Process

Mode A: Create New Skill

1. Create skill directory with SKILL.md, README.md, AGENTS.md
2. Edit SKILL.md following Rules below
3. Edit README.md with Japanese translation
4. Run agent-tools skill validate <path> to check
5. Fix any errors or warnings

Mode B: Modify Existing Skill

1. Read all files in the skill directory
2. Apply modifications following Rules below
3. Sync README.md with SKILL.md changes
4. Run agent-tools skill validate <path> to check

Mode C: Validate Skill

1. Run agent-tools skill validate <path>
2. Fix errors before proceeding
3. Check against Rules below
4. Verify README.md matches SKILL.md content
5. Report issues with location and suggested fix

Rules

name

• Gerund form: processing-pdfs, analyzing-data
• Alternatives: pdf-processing, process-pdfs
• Avoid: helper, utils, documents
• Regex: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$, max 64 chars, no consecutive hyphens

description

Format: [Feature description]. Use when [trigger conditions].

• Third person: "Creates...", "Analyzes..."
• 100-300 chars recommended, max 1024
• No < >

Good: Scans Algorand smart contracts for 11 common vulnerabilities. Use when auditing Algorand projects.

Bad: For async testing (too vague), I can help you... (first person)

Optional Fields

license: MIT
allowed-tools: Read, Edit
metadata:
  author: name
  version: "1.0.0"
user-invocable: true
disable-model-invocation: false
argument-hint: <arg>

Structure

Required sections: Overview, When to Use, The Process, Tips (additional sections like Contents, Rules allowed)

Files over 100 lines need table of contents at top (include subsections).

Progressive Disclosure

Design Principle: Level 3 may not be read.

• Rules that must be applied → Level 2 (SKILL.md body)
• Brief examples allowed in Level 2; extensive examples → Level 3 (references/)
• Skill must work correctly even if Level 3 is never read

Directory Structure

skill-name/
├── SKILL.md                # Required
├── README.md               # Japanese (for multilingual)
├── AGENTS.md               # Sync instructions
├── references/             # Optional, 1 level depth only
├── scripts/
└── assets/

Not recommended: INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md

Script Design

• Single responsibility
• Explicit error handling
• JSON/markdown output
• No sensitive info in logs
• Check usage with --help before execution

Content Principles

Core:

1. Conciseness (Claude is already smart)
2. Consistent terminology
3. Concrete examples

Avoid:

• Time-dependent info ("As of 2024...")
• Long option lists (brief alternatives OK)
• Windows paths
• First person ("I can help...")

Multilingual

• SKILL.md: English
• README.md: Japanese translation
• AGENTS.md: sync instructions

Static Analysis

Error checks (exit code 1):

• SKILL.md existence, frontmatter format, YAML parsing
• Required fields (name, description)
• Name format/length, description forbidden chars/length

Warning checks (exit code 2):

• Line count > 500, word count > 5000
• Forbidden files, reference depth > 1
• Missing table of contents in 100+ line files

Tips

• Common mistakes: first person in description, missing "Use when", vague names
• Place important info at file top (Claude may preview partially)
• Keep references/ to 1 level depth only (nested references read incompletely)