skill-creator

Skill Creator for DaleStudy

A guide for adding a new skill to the DaleStudy/skills repository.

Skill structure

skills/{skill-name}/
└── SKILL.md          # YAML frontmatter + Markdown 지시사항 (필수)

SKILL.md format

---
name: skill-name # 필수: 디렉토리명과 일치 (최대 64자, 소문자/숫자/하이픈)
description: "스킬 설명" # 필수: 트리거 조건 포함 (최대 1024자)
license: MIT # 선택
compatibility: Required CLI tools # 선택: 필요한 도구
metadata: # 선택
  author: DaleStudy
  version: "1.0.0"
allowed-tools: Bash(command:*) # 선택: 허용할 도구 패턴
---
# 스킬 제목

스킬 지시사항 (Markdown)

Skill creation procedure

1. Create directory

mkdir -p skills/{skill-name}

2. Write SKILL.md

Frontmatter writing rules

name field:

Must be the same as the directory name
Use only lowercase letters, numbers, and hyphens
Consecutive hyphens not allowed (my--skill ❌)
Maximum 64 characters

description field (most important):

The skill's purpose and trigger conditionsmust be clearly described
Because the body is loaded only after triggering, "when to use" must be included in the description
Pattern: "{스킬 설명}. 다음 상황에서 사용: (1) ..., (2) ..., (3) ..."

# ✅ 좋은 예
description: "Node.js 대신 Bun 런타임 사용을 위한 스킬. 다음 상황에서 사용: (1) 새 JavaScript/TypeScript 프로젝트 생성 시, (2) package.json 또는 의존성 관련 작업 시"

# ❌ 나쁜 예
description: "Bun 관련 스킬"  # 트리거 조건 없음

Body writing rules

Keep it concise (500 lines or fewer recommended)
Omit content Claude already knows
Example code > verbose explanations
Use imperative/infinitive form

3. Update README.md

Add the new skill to README.md at the repository root:

## Current Skills

- **bun**: Node.js 대신 Bun 런타임 사용
- **github-actions**: GitHub Actions 워크플로우 작성 및 보안
- **{new-skill}**: {간단한 설명} <!-- 추가 -->

4. Update the workflow matrix

.github/workflows/ci.ymlAdd the new skill to the matrix in :

matrix:
  skill:
    - bun
    - github-actions
    - { new-skill } # 추가

Refer to existing skills

Skill	Features
`bun`	Command mapping table, example-code focused
`github-actions`	Security best practices, YAML example focused
`skill-creator`	Meta skill, structured procedures, frontmatter guide
`storybook`	CSF 3.0 best practices, TypeScript type examples

When writing a new skill, refer to the style of existing skills to maintain consistency.

Version management

Follow Semantic Versioning (MAJOR.MINOR.PATCH) and update the version when modifying a skill:

MAJOR version (x.0.0)

Breaking changes - Impact on existing users:

Adding/changing required Frontmatter fields
allowed-tools Reducing permissions
Major changes to skill trigger conditions (modifying description)
Introducing new rules that conflict with existing instructions

# 예: 1.2.3 → 2.0.0
metadata:
  version: "2.0.0"

MINOR version (0.x.0)

Adding new features - Maintaining backward compatibility:

Adding new example code
Adding instruction sections (no conflict with existing ones)
allowed-tools Expanding permissions
Expanding trigger conditions (maintaining existing conditions)

# 예: 1.2.3 → 1.3.0
metadata:
  version: "1.3.0"

PATCH version (0.0.x)

Bug fixes and minor improvements:

Fixing typos
Clarifying descriptions (no change in meaning)
Cleaning up code example formatting
Updating links

# 예: 1.2.3 → 1.2.4
metadata:
  version: "1.2.4"

Version update checklist

CRITICAL: You must update the version every time you modify a skill's SKILL.md file.

After modifying a skill:

Determine whether the change corresponds to MAJOR/MINOR/PATCH
metadata.version Field update (required)
(Optional) Write CHANGELOG.md (for major changes)

A version not being updated is considered a skill validation failure.

Automatic validation when a skill changes

IMPORTANT: When modifying the SKILL.md file, be sure to check the following:

1. Version update validation

If the SKILL.md file has been modified, metadata.versionmust also be updated together:

# 변경된 SKILL.md 확인
git diff --name-only HEAD | grep "skills/.*/SKILL.md"

# 또는 커밋 전 staged 파일 확인
git diff --cached --name-only | grep "skills/.*/SKILL.md"

# metadata.version 필드가 변경되었는지 확인
git diff HEAD -- skills/{skill-name}/SKILL.md | grep "^\+.*version:"
git diff --cached -- skills/{skill-name}/SKILL.md | grep "^\+.*version:"

# 변경되지 않았다면:
# ❌ ERROR: skills/{skill-name}/SKILL.md was modified but metadata.version was not updated
# Required: Update version according to Semantic Versioning (see 버전 관리 section above)

2. Version increment direction validation

Check whether the change follows the correct version increment:

A MAJOR change but a MINOR/PATCH increment: ❌ Error
A MINOR change but a PATCH increment: ⚠️ Warning
A PATCH change but a MINOR/MAJOR increment: ✅ Allowed (conservative increments are safe)

3. Frontmatter validity validation

name Does the field match the directory name?
description Does the field include the trigger conditions? ("Use in the following situations:" pattern)
metadata.version Is the format "X.Y.Z" (Semantic Versioning)?

Manual validation

Skill installation test:

npx skills add DaleStudy/skills --skill {skill-name} --agent claude-code --global --yes