zakelfassi/skills-driven-development

SkillForge

관찰된 패턴에서 잘 구성되고 스펙을 준수하는 스킬을 생성합니다.

단조(Forge) 시점

✅ 단조해야 할 때:

• 세션 내에서 동일한 작업을 2~3회 반복한 경우
• 프로젝트 규칙이 어디에도 문서화되지 않은 경우
• 어려운 문제를 재사용 가능한 솔루션으로 해결한 경우
• 누군가 스킬 생성을 요청한 경우

❌ 단조하지 말아야 할 때:

• 일회성 작업인 경우
• 기존 스킬이 이미 해당 작업을 다루고 있는 경우 (대신 업데이트)
• '스킬'이 단일 명령어에 불과한 경우 (스크립트 별칭 사용)

단계

1. 패턴 이름 짓기

• 이 스킬은 어떤 문제를 해결하나요?
• 무엇이 이 스킬을 트리거하나요? (구체적으로 작성하세요 — description 필드가 검색 창구입니다)
• 입력과 출력은 무엇인가요?

2. 이름 선택하기

• kebab-case, 1~64자
• 가능하면 동사로 시작: deploy-preview, scaffold-component, triage-bug
• 스킬 하나당 하나의 책임

3. 스킬 디렉토리 생성

mkdir -p skills/<skill-name>

4. SKILL.md 작성

다음 뼈대를 사용하세요:

---
name: <skill-name>
description: <무엇을 하는지>. <트리거가 발생할 때> 사용.
metadata:
  forged-by: <agent-id>
  forged-from: <session-or-context>
  forged-reason: "<이 스킬이 생성된 이유>"
---

# <Skill Name>

## 입력
- ...

## 단계
1. ...
2. ...

## 규칙
- 해당 프로젝트에 적용되는 패턴

## 엣지 케이스
- 알려진 문제점 또는 특수 처리 방법

5. 스크립트 추가 (선택 사항)

스킬이 파일 생성이나 자동화를 포함하는 경우:

skills/<skill-name>/
├── SKILL.md
├── scripts/
│   └── run.sh         # 실행 가능한 자동화 스크립트
└── references/
    └── conventions.md # 상세 참고 자료 (SKILL.md를 간결하게 유지)

6. 스킬 등록

프로젝트 루트 (skills/와 같은 레벨)에서 .skills-registry.md를 업데이트하세요. 파일이 없으면 생성합니다:

| <skill-name> | local | <today> | 1 | <description> |

프로젝트가 기계 판독 가능한 레지스트리(.skills-registry.json)를 사용한다면 함께 업데이트하세요 — skdd forge는 두 형식을 자동으로 처리합니다.

기존 스킬 업데이트

스킬을 사용하다가 스킬이 다루지 않는 상황을 만나면:

1. 기존 SKILL.md에 새로운 엣지 케이스나 단계를 추가합니다.
2. 스킬이 너무 길어지면(200줄 초과) 분할합니다.
3. 레지스트리에서 last-used를 업데이트하고 usage-count를 증가시킵니다.

품질 체크리스트

새 스킬을 커밋하기 전에:

• name이 kebab-case이고 64자 이하인가?
• description에 무엇을 하는지와 언제 사용해야 하는지가 포함되었는가?
• 단계가 번호로 매겨져 있고 실행 가능한가?
• 하드코딩된 경로, 비밀, 또는 환경별 값이 없는가?
• SKILL.md가 200줄 미만인가? (세부 내용은 references/로 이동)
• .skills-registry.md에 등록되었는가?