| name | skill-guide |
| description | Use when user wants to create a new Skill, validate SKILL.md structure, or reference Anthropic skill design guide. Do NOT use for eval-based improvement or benchmark testing (use skill-creator plugin). |
Skill Guide
Frontmatter Spec
Every skill needs a SKILL.md file (exact casing) in a kebab-case directory.
---
name: skill-name
description: What it does and when to use it.
---
Naming rules: lowercase, numbers, hyphens only. No "claude" or "anthropic" prefix.
Optional fields:
allowed-tools: "Read Grep Glob"
license: MIT
compatibility: "Claude Code only"
metadata:
author: Name
version: 1.0.0
tags: [automation, workflow]
Description Writing
Description은 요약이 아니라 트리거 판단 기준이다. Claude가 세션 시작 시 모든 스킬의 description을 스캔해서 로드 여부를 결정한다.
Formula: [What it does] + [When to use it] + [Negative triggers]
description: Analyze Excel spreadsheets, create pivot tables, and generate charts.
Use when working with .xlsx files or analyzing tabular data.
Do NOT use for CSV-only operations (use data-processor skill).
description: Helps with data analysis
Skill Location
| Location | Use for |
|---|
~/.claude/skills/ | Personal workflows, experiments |
.claude/skills/ | Team/project, committed to git |
File Structure
스킬은 폴더다. SKILL.md 하나가 아니다.
skill-name/
├── SKILL.md # Required — 핵심 지시사항 (5,000 words 이내)
├── references/ # Claude가 필요할 때 읽는 상세 문서
├── scripts/ # 결정적(deterministic) 검증/처리용 스크립트
└── assets/ # Templates, data files
파일 시스템 자체가 progressive disclosure다. SKILL.md에서 어떤 파일이 있는지 알려주면, Claude가 적절한 시점에 읽는다. SKILL.md에 모든 내용을 넣지 말 것.
Content Writing Principles
Don't State the Obvious
Claude는 코딩, 마크다운 구조화, 에지 케이스 처리를 이미 안다. Claude의 일반적 사고방식을 벗어나게 하는 정보에 집중하라 — 조직의 컨벤션, 도메인 특화 gotchas, 비직관적 패턴.
Build a Gotchas Section
스킬에서 가장 가치 있는 콘텐츠는 Gotchas 섹션이다. Claude가 실제로 틀리는 지점을 기록하고, 시간이 지나며 축적하라.
## Gotchas
- API returns paginated results but doesn't indicate total count — always loop until empty
- The `--dry-run` flag silently ignores invalid configs instead of erroring
- Date fields use ISO 8601 but timezone is always UTC regardless of user locale
Avoid Railroading
정보는 주되, Claude가 상황에 맞게 적응할 유연성을 남겨라. 모든 상황에 적용되는 rigid step sequence를 강제하지 말 것.
# ❌ 과도한 제약
## Step 1: Always create the config file first
## Step 2: Then validate the schema
## Step 3: Then run the migration
# ✅ 유연한 가이드
## Setup
Ensure config exists (see references/config-schema.md for required fields).
Validate before running migrations — migration order matters,
check references/migration-deps.md for dependency graph.
Use Scripts for Determinism
스크립트는 결정적이고, 자연어 지시는 아니다. 중요한 검증이나 출력 포맷은 scripts/에 코드로 번들하라.
Troubleshooting
| 증상 | 원인 | 해결 |
|---|
| 스킬이 트리거 안됨 | description이 모호 | 트리거 문구, 파일 타입, "Use when..." 추가 |
| 무관한 쿼리에서 트리거 | description이 넓음 | "Do NOT use for..." negative trigger 추가 |
| 여러 스킬 충돌 | description 겹침 | 각 스킬의 범위를 구체적으로 좁힘 |
| YAML 파싱 에러 | 포맷 오류 | --- 구분자, 탭 대신 스페이스, 따옴표 닫기 확인 |
| 원인 불명 | — | claude --debug로 스킬 로딩 과정 확인 |
References
