What is create-skill?

This Claude skill provides a comprehensive framework and standardized guide for developing, structuring, and packaging agentic skills. It ensures high discoverability and reusability of AI workflows by defining strict YAML frontmatter requirements, naming conventions, and directory structures compatible with Agentic Terminal User Interfaces (ATUI). By implementing these best practices, developers can create modular, project-agnostic capabilities that enhance the consistency and performance of AI agents.

When should I use create-skill?

create-skill is useful in the following scenarios: • Standardizing skill development: Establish a uniform file structure and naming convention across a development team to ensure all AI agent skills are consistent and maintainable. • Optimizing skill discovery: Use the specific YAML frontmatter and description guidelines to help AI agents accurately identify and invoke the correct skill for a given task. • Building reusable workflow libraries: Create a repository of project-agnostic skills (like TDD or code review) that can be easily integrated into different agentic environments. • Scaling agentic infrastructure: Facilitate the growth of complex agent systems by organizing supporting files and templates in a way that minimizes redundancy and maximizes modularity.

name	create-skill
description	Use when creating or modifying skills. Defines skill file structure, naming conventions, and integration patterns.

Creating Agent Skills

Overview

Skills in for Agents provide reusable workflows and guidelines. This skill documents how to properly create new skills.

Required File Structure

These skills are designed to be Agentic Terminal User Interface (ATUI) agnostic. They live in the dotfolders for the agentic application examples include.

.claude/
.codex/
.gemini/
.opencode/

Henceforth, we will use .atui/ as shorthand

Every skill must have:

.atui/skills/skill-name/
├── SKILL.md (REQUIRED - main skill file with frontmatter)
├── supporting-file.md (optional)
└── templates/ (optional)

SKILL.md Requirements

1. YAML Frontmatter (REQUIRED)

Every SKILL.md must start with YAML frontmatter:

---
name: skill-name
description: Brief description of what this skill does and when to use it
---

Frontmatter Rules:

name: Lowercase letters, numbers, hyphens only (max 64 chars)
description: Explain WHAT it does + WHEN to use it (max 1024 chars)
Critical: ATUIs use description for automatic skill discovery

2. Main Content

After frontmatter, elicit the human to add the skill instructions in markdown:

Skill Naming Conventions

DO:

✅ Use lowercase letters
✅ Use hyphens for word separation
✅ Make names descriptive but concise
✅ Keep under 64 characters

DON'T:

❌ Use uppercase letters
❌ Use underscores
❌ Use spaces
❌ Use special characters

Examples:

✅ create-skill
✅ test-driven-development
✅ write-commit-message
❌ Create_Skill
❌ test driven development

Description Best Practices

The description is critical for skill discovery and invocation.

Purpose: Help Claude decide whether to READ the skill, not to contain the rules themselves.

Format: "Use when [specific trigger]. Defines [what's inside]."

Guidelines:

Start with trigger: Begin with "Use when [action/situation]"
Be concise: Keep under 200 characters if possible
Specific triggers: Include clear conditions for when to invoke

Supporting Files

Skills can include additional files referenced from SKILL.md:

For Python testing: See [PYTHON.md](PYTHON.md)
For JavaScript testing: See [JAVASCRIPT.md](JAVASCRIPT.md)

Common Supporting Files:

Language-specific guides (PYTHON.md, JAVASCRIPT.md)
Templates (TEMPLATE.md, templates/spec-template.md)
Examples (EXAMPLES.md)
Scripts (scripts/helper.py)

Additionally register skills to the projects AGENTS.md file.

Creation Checklist

When creating a new skill:

Create directory: .atui/skills/skill-name/
Create SKILL.md with YAML frontmatter
Add name field (lowercase, hyphens, max 64 chars)
Add description field (WHAT + WHEN, max 1024 chars)
Ask human to add more details and and supporting files
Reference supporting files with relative paths
Test skill discovery with /help
Regiser skill to AGENTS.md

Allows follow these practices

✅ Always include frontmatter - SKILL.md must start with YAML frontmatter ✅ Write clear descriptions - Description must explain WHAT and WHEN ✅ Use correct filename - Must be SKILL.md (uppercase) ✅ Use proper naming - Use lowercase letters and hyphens for separation ✅ Be specific - Clearly define when to use the skill ✅ Keep content generic - Do not make guidelines specific to the current project but Make SKILL.md and supporting files reusable across projects ✅ Separate language specifics - Put language/tech-specific details in separate files (PYTHON.md, RUST.md, etc.) ✅ Provide complete templates - Include full templates, not partial ones ✅ Prioritize clear descriptions - Avoid examples or use generic examples only when necessary for clarity ✅ Work in small steps - Only implement what was requested, collaborate incrementally in small steps with the user ✅ Use positive framing - Describe what to do rather than what not to do when writing guidelines but use negatives when it provides extra clarity

Skill Integration

Skills can reference other skills:

**Use the `specification` skill for writing specifications.**
**Use the `test-driven-development` skill for writing tests.**

This creates workflows that combine multiple skills.

Testing Your Skill

After creating a skill:

Run /help to verify it's discovered
Check the description appears correctly
Test invoking the skill in context
Verify supporting files load correctly

Reference

Official documentation: https://code.claude.com/docs/en/skills.md

create-skill

When & Why to Use This Skill

Use Cases