skill-creator

Skill Creator

This SKILL provides guidelines for creating effective SKILLs.

About SKILLs

A SKILL is a modular, self-contained package that extends Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of it as an "onboarding guide" for a specific domain or task. SKILLs transform Claude from a general agent into a specialized agent with procedural knowledge that a specific model cannot fully possess on its own.

What SKILLs Provide

Specialized workflows - Multi-step procedures for specific domains
Tool integration - Instructions for working with specific file formats or APIs
Domain expertise - Company-specific knowledge, schemas, business logic
Bundled resources - Scripts, reference documents, and assets for complex and repetitive tasks

Core Principles

Concise is Key

The context window is like a public good. A SKILL shares context space with everything Claude needs, including the system prompt, conversation history, metadata from other SKILLs, and the actual user request.

Default premise: Claude is already smart enough. Add only the context Claude does not yet have. For each piece of information, ask yourself: "Does Claude really need this explanation?", "Is this paragraph worth the tokens it consumes?"

Prefer concise examples over verbose explanations.

Set Appropriate Degrees of Freedom

Adjust the level of specificity to match the fragility and variability of the task:

High degree of freedom (text-based instructions): Use when multiple approaches are valid, when the decision depends on context, or when heuristics guide the approach.

Medium degree of freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, when slight variation is allowed, or when configuration affects behavior.

Low degree of freedom (specific scripts, few parameters): Use when the task is fragile and error-prone, when consistency is important, or when a specific order must be followed.

Imagine Claude navigating a path: a narrow bridge with cliffs requires specific guardrails (low degree of freedom), while an open field allows for various routes (high degree of freedom).

Anatomy of a Skill

Every SKILL consists of the required file SKILL.md and optional bundled resources:

skill-name/
├── SKILL.md (필수)
│   ├── YAML frontmatter metadata (필수)
│   │   ├── name: (필수)
│   │   └── description: (필수)
│   └── Markdown 지침 (필수)
└── Bundled Resources (선택 사항)
    ├── scripts/          - 실행 가능한 코드 (Python/Bash 등)
    ├── references/       - 필요에 따라 컨텍스트에 로드할 문서
    └── assets/           - 출력물에 사용될 파일 (템플릿, 아이콘, 폰트 등)

SKILL.md (required)

Every SKILL.md consists of the following:

Frontmatter (YAML): name과 description Includes the field. Since this is the only field Claude reads to decide whether to use the SKILL, it is very important to clearly and comprehensively explain what the SKILL is and when it should be used.
Body (Markdown): Instructions and guidance for using the SKILL. It is loaded only 'after' the SKILL is triggered.

Bundled Resources (Optional)

Scripts (`scripts/`)

Executable code (Python/Bash, etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

When to include: When the same code is repeatedly written or deterministic reliability is required
Example: For PDF rotation tasks scripts/rotate_pdf.py
Advantages: Token-efficient and deterministic, and can be executed without loading into context
Note: Claude may need to read the script for patching or environment-specific adjustments

Reference Documents (`references/`)

Documents and reference materials intended to be loaded into context as needed to assist Claude's process and thinking.

When to include: When there are documents Claude needs to reference during the task
Example: For financial schemas references/finance.md, for company NDA templates references/mnda.md, for company policies references/policies.md, for API specifications references/api_docs.md
Use cases: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
Advantages: Keeps SKILL.md lightweight, and is loaded only when Claude determines it is needed
Best practices: If the file is large (>10k words), include grep search patterns in SKILL.md.
Avoid duplication: Information should exist in only one place, either in SKILL.md or in a reference file. To reduce context window usage while maintaining information discoverability, prefer placing detailed information in reference files unless it is truly essential guidance. Keep only essential procedural instructions and workflow guidance in SKILL.md, and move detailed reference materials, schemas, and examples to reference files.

Assets (`assets/`)

Files not intended to be loaded into context, but intended to be used within the output Claude generates.

When to include: When the SKILL requires files to be used in the final output
Example: For brand assets assets/logo.png, for PowerPoint templates assets/slides.pptx, for HTML/React boilerplate assets/frontend-template/, for typography assets/font.ttf
Use cases: Templates, images, icons, boilerplate code, fonts, sample documents to copy or modify and use
Advantages: Separate output resources from documents, allowing Claude to use them without loading files into context

What should not be included in a SKILL

A SKILL should include only the essential files that directly support its functionality. Do not create unnecessary documents or auxiliary files such as the following:

README.md
INSTALLATION_GUIDE.md
QUICK_REFERENCE.md
CHANGELOG.md
etc.

A SKILL should include only the information needed for the AI agent to perform the given task. Do not include incidental context about the production process, setup and testing procedures, user documentation, etc. Unnecessary documentation files only add confusion.

Progressive Disclosure Design Principle

A SKILL uses a 3-level loading system to manage context efficiently:

Metadata (name + description) - Always present in context (~100 words)
SKILL.md body - Loaded when the SKILL is triggered (<5k words)
Bundled resources - Loaded when Claude needs them (scripts can be executed without loading into context, so there is no size limit)

Progressive Disclosure Patterns

To minimize context bloat, keep the SKILL.md body under 500 lines, focusing on essentials. When you reach this limit, split the content into separate files. When splitting content into other files, it is very important to reference them in SKILL.md and clearly explain when to read them, so that the model reading the SKILL knows that the file exists and when to use it.

Key principles: If a SKILL supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move details specific to a particular variation (patterns, examples, configurations) to separate reference files.

Pattern 1: High-level guide with reference documents

# PDF Processing

## 빠른 시작

pdfplumber로 텍스트 추출:
[코드 예시]

## 고급 기능

- **폼 채우기(Form filling)**: 전체 가이드는 [FORMS.md](FORMS.md) 참조
- **API 참조**: 모든 메서드는 [REFERENCE.md](REFERENCE.md) 참조
- **예시**: 일반적인 패턴은 [EXAMPLES.md](EXAMPLES.md) 참조

Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.

Pattern 2: Domain-specific organization

For a SKILL with multiple domains, organize content by domain to avoid loading irrelevant context:

bigquery-skill/
├── SKILL.md (개요 및 탐색)
└── reference/
    ├── finance.md (매출, 청구 지표)
    ├── sales.md (기회, 파이프라인)
    ├── product.md (API 사용량, 기능)
    └── marketing.md (캠페인, 어트리뷰션)

When the user asks about sales metrics, Claude reads only sales.md.

Likewise, a SKILL that supports multiple frameworks or variations should be organized by variation:

cloud-deploy/
├── SKILL.md (워크플로우 + 프로바이더 선택)
└── references/
    ├── aws.md (AWS 배포 패턴)
    ├── gcp.md (GCP 배포 패턴)
    └── azure.md (Azure 배포 패턴)

When the user chooses AWS, Claude reads only aws.md.

Pattern 3: Conditional details

Show the basic content and provide links to advanced content:

# DOCX Processing

## 문서 생성

새 문서에는 docx-js를 사용하세요. [DOCX-JS.md](DOCX-JS.md) 참조.

## 문서 편집

단순한 편집의 경우 XML을 직접 수정하세요.

**수정 내용 추적(tracked changes)의 경우**: [REDLINING.md](REDLINING.md) 참조
**OOXML 세부 사항의 경우**: [OOXML.md](OOXML.md) 참조

Claude reads REDLINING.md or OOXML.md only when the user needs that feature.

Important guidelines:

Avoid deeply nested references - Keep references only one level deep from SKILL.md. All reference files should be linked directly from SKILL.md.
Structure long reference files - For files with more than 100 lines, include a table of contents at the top so Claude can grasp the full scope when previewing.

SKILL Creation Process

SKILL creation consists of the following steps:

Understand SKILL through concrete examples (Understand)
Plan reusable SKILL content (Plan)
Initialize SKILL (run init_skill.py)
Edit SKILL (implement resources and write SKILL.md)
Package SKILL (run package_skill.py)
Iterate based on actual usage (Iterate)

Follow these steps in order unless there is a valid reason not to.

Step 1: Understand SKILL through concrete examples

Skip this step only if the usage patterns of the SKILL are already clearly understood. This step is also valuable when improving an existing SKILL.

To create an effective SKILL, you must clearly understand concrete examples of how the SKILL will be used. This can be achieved through direct user examples or generated examples validated through user feedback.

For example, when building an image-editor SKILL, the following questions are helpful:

"What features should the image-editor SKILL support? Editing, rotating, and what else?"
"Could you give me a few examples of how this SKILL will be used?"
"Users will likely make requests like 'remove red-eye from this image' or 'rotate this image'—are there any other use cases?"
"What would a user say that should trigger this SKILL?"

To avoid burdening the user, do not ask too many questions in a single message. Start with the most important questions and ask follow-up questions as needed to improve effectiveness.

This step ends once you have a clear sense of the features the SKILL should support.

Step 2: Plan reusable SKILL content

To turn concrete examples into an effective SKILL, analyze each example as follows:

Consider how to execute that example from scratch
Identify scripts, reference documents, and assets that would help when executing this workflow repeatedly

Example: For handling queries like "rotate this PDF", pdf-editor Analysis when building a SKILL:

Rotating a PDF requires rewriting the same code every time
scripts/rotate_pdf.py Storing the script in the SKILL would be helpful

Example: For handling queries like "make me a to-do app" or "make me a dashboard to track my step count", frontend-webapp-builder Analysis when designing a SKILL:

Writing a frontend web app requires the same boilerplate HTML/React every time
Including boilerplate HTML/React project files assets/hello-world/ Saving the template in the SKILL is helpful

Example: For handling a query like "How many users logged in today?" big-query Analysis when building the SKILL:

Every time you query BigQuery, you have to recheck the table schema and relationships each time
Documenting the table schema in a references/schema.md Saving the file in the SKILL is helpful

To establish the content of the SKILL, analyze each concrete example and create a list of reusable resources (scripts, reference documents, assets) to include.

Step 3: Initialize the SKILL

Now it is time to actually create the SKILL.

If the SKILL you want to develop already exists and only needs improvement or packaging, skip this step and proceed to the next step.

When creating a new SKILL from scratch, always init_skill.py Run the script. This script creates a new template SKILL directory that automatically includes everything needed for the SKILL, making the creation process much more efficient and reliable.

Usage:

scripts/init_skill.py <skill-name> --path <output-directory>

This script:

Create a SKILL directory at the specified path
Create a SKILL.md template with correct frontmatter and TODO location markers
Create example resource directories: scripts/, references/, assets/
Add example files for each directory that can be customized or deleted

After initialization, customize or delete the generated SKILL.md and example files as needed.

Step 4: Edit the SKILL

When editing a SKILL (whether newly created or existing), keep in mind that this SKILL is made for use by other instances of Claude. Include information that is useful yet non-obvious to Claude. Consider what procedural knowledge, domain details, or reusable assets would help other Claude instances perform these tasks more effectively.

Learning proven design patterns

Refer to the following guides as needed for the SKILL:

Multi-step processes: For sequential workflows and conditional logic, refer to references/workflows.md.
Specific output formats or quality standards: For templates and example patterns, refer to references/output-patterns.md.

These files contain proven best practices for effective SKILL design.

Start with reusable SKILL content

To begin implementation, start by writing the reusable resource (scripts/, references/, assets/) files identified above. This step may require user input. For example, brand-guidelines When implementing the SKILL, the user may need to provide assets/brand assets or templates to save in, or references/documents to save in.

Added scripts must actually be executed to test that there are no bugs and that the output matches expectations. If there are many similar scripts, you only need to test representative samples, so that reliability can be ensured while adjusting the completion time.

Example files and directories not needed for the SKILL should be deleted. The initialization script creates example files in each directory to show the structure, but most SKILLs do not need all of them.

SKILL.md update

Writing guidelines: Always use the imperative/infinitive form.

Frontmatter

name과 description Write YAML frontmatter with the fields:

name: SKILL name
description: This is the main trigger mechanism of the SKILL and helps Claude understand when this SKILL should be used.
- Include both what the SKILL does and specific triggers/context for when it should be used.
- Include all information about "when to use" here, not in the body. Because the body is loaded after being triggered, a "When to Use This Skill" section in the body does not help Claude.
- docx Example description of a SKILL: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, format preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) creating new documents, (2) modifying or editing content, (3) working with tracked changes, (4) adding comments or other document-related tasks"

Do not include other fields in the YAML frontmatter.

Body

Write instructions for using the SKILL and bundled resources.

Step 5: SKILL packaging

Once SKILL development is complete, it must be packaged into a distributable .skill file to share with users. The packaging process first automatically validates the SKILL to ensure it meets all requirements:

scripts/package_skill.py <path/to/skill-folder>

Specify an optional output directory:

scripts/package_skill.py <path/to/skill-folder> ./dist

The packaging script does the following:

Validate: Automatically inspects the SKILL and checks the following:
- YAML frontmatter format and required fields
- SKILL naming conventions and directory structure
- Completeness and quality of the description
- File organization and resource references
Package: If validation passes, creates a .skill file named after the SKILL (e.g., my-skill.skill) containing the appropriate directory structure and all files for distribution. A .skill file is a zip file with the .skill extension.

If validation fails, the script reports the error and exits without creating a package. Fix the validation errors and rerun the packaging command.

Step 6: Iterate and improve

After testing a SKILL, the user can request improvements. This usually happens immediately after use, when vivid context about how the SKILL worked is still available.

Iterative workflow:

Use the SKILL for real work
Discover difficulties or inefficient parts
Identify how SKILL.md or bundled resources should be updated
Implement changes and retest