Files

minsung cb5efd591f chore: update project docs and add local config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-09 09:08:35 +09:00

7.1 KiB

Raw Permalink Blame History

Skills 문서

작성: 2026-04-08 대상: workhistory 저장소의 .claude/skills/ 하위 프로젝트 스킬

1. Skills 란?

Claude Code 의 Skill 은 특정 상황에서 Claude 가 자동으로(또는 사용자가 슬래시 커맨드로) 참조하는 작업 지식 꾸러미다. SKILL.md 파일의 YAML 프론트매터에 name 과 description 을 선언하면, Claude 는 사용자의 메시지가 그 description 과 매칭될 때 해당 스킬 문서를 컨텍스트로 끌어온다.

설치 위치: .claude/skills/<skill-name>/SKILL.md (프로젝트 단위) 또는 ~/.claude/skills/ (전역)
트리거 방식
- 자동: description 키워드와 사용자 메시지 매칭 시 Claude 가 자발적으로 로드
- 수동: /skill-name 슬래시 커맨드로 사용자가 직접 호출

형식: 프론트매터 + 본문 마크다운

---
name: my-skill
description: <어떤 상황에서 써야 하는지 한 줄 설명>
---

# 본문 (절차, 설정, 트러블슈팅 등)

2. 이 저장소에 등록된 스킬

스킬	경로	트리거 키워드
`aptabase`	.claude/skills/aptabase/SKILL.md	"aptabase 설정", "aptabase 테스트", "토큰 기록 확인", "누적 토큰"

현재 프로젝트 스킬은 aptabase 하나뿐이다.

3. `aptabase` 스킬

3.1 목적

Aptabase 커밋 기준 토큰 기록 훅(.claude/hooks/ 하위)의 설치·검증·디버깅 절차를 Claude 가 필요할 때 즉시 참조할 수 있도록 묶어둔 운영 가이드다.

사용자가 다음과 같은 요청을 하면 Claude 가 이 스킬을 자동 로드한다:

"aptabase 설정 해줘"
"aptabase 연결 테스트해봐"
"토큰 기록이 제대로 되고 있는지 확인해줘"
"누적 토큰이 얼마나 쌓였어?"

또는 수동으로 /aptabase 를 입력해도 동일하게 호출된다.

3.2 스킬 문서가 담고 있는 내용

SKILL.md 는 다음 섹션으로 구성되어 있다:

구조 — .claude/hooks/, .claude/state/, .git/hooks/ 의 파일 구성
동작 방식 — Stop / PostToolUse(Bash) / post-commit 세 진입점의 역할표와 순서도
설정 — aptabase.json 의 각 키 의미 (enabled, app_key, aptabase_host, user_name)
settings.json 등록 방법 — Stop 훅과 PostToolUse(Bash) 훅 예시
git post-commit 훅 설치 — install-git-hook.sh 사용법, --force / --uninstall 옵션
전송 payload — claude_commit 이벤트의 systemProps / props 필드 스키마
연결 테스트 3단계 — curl 직접 POST → Stop 훅 수동 실행 → 실제 E2E
누적 상태 파일 포맷 — aptabase-accum.json 의 필드 설명
트러블슈팅 — accum 이 0 으로 고정되는 경우, 커밋했는데 Aptabase 에 안 뜨는 경우, 첫 커밋이 무시되는 경우, 기준점 초기화 명령

3.3 실제 활용 시나리오

시나리오 A — 신규 프로젝트에 훅 설치

사용자: "이 프로젝트에 aptabase 훅 붙여줘" → Claude 가 aptabase 스킬을 로드 → SKILL.md 의 "1. 설정" ~ "2-1. git post-commit 훅 설치" 절차를 따라 파일 복사, aptabase.json 작성, settings.json 수정, install-git-hook.sh 실행까지 자동 수행.

시나리오 B — 기록이 안 되는 것 같을 때

사용자: "토큰 기록이 안 되는데 확인해줘" → Claude 가 스킬을 로드 → SKILL.md 의 "연결 테스트 3단계" 를 순서대로 실행(curl 도달성 → Stop 훅 수동 → state 파일 확인) → "트러블슈팅" 체크리스트와 대조해 원인 보고.

시나리오 C — 누적 상태 확인

사용자: "지금 누적 토큰 얼마야?" → Claude 가 스킬을 로드 → .claude/state/aptabase-accum.json 을 읽고 필드별(input / cache_creation / cache_read / output / consumed) 로 요약.

4. 새 스킬 추가 절차

이 저장소에 스킬을 하나 더 추가하려면:

디렉터리 생성
```
mkdir -p .claude/skills/<skill-name>
```
SKILL.md 작성 — 프론트매터 필수
```
---
name: <skill-name>
description: <한 줄로 "어떤 요청이 왔을 때 써야 하는지" 명확히 서술. 이 문장이 자동 트리거의 유일한 근거다.>
---

# 본문
...
```
description 은 Claude 가 스킬을 언제 부를지 판단하는 유일한 힌트다. 모호한 문구("유용한 도구")는 트리거가 잘 안 되고, 키워드("X 설정", "Y 디버깅")를 명시할수록 잘 걸린다.
본문 작성 가이드
- 사용자가 요청할 만한 상황을 먼저 나열
- 그 상황에서 따라야 할 구체적 절차 (명령, 경로, 체크리스트)
- 자주 발생하는 실패 케이스와 대응
- 관련 파일 경로를 상대 링크로 걸어 Claude 가 바로 읽을 수 있게
커밋 — .claude/skills/ 는 버전 관리 대상. 팀원/다음 세션이 동일하게 쓸 수 있도록 커밋한다.
테스트 — 다음 세션에서 description 에 적힌 키워드로 질문해 자동 로드되는지 확인하거나, /skill-name 으로 직접 호출.

5. 사용자 invocation — 슬래시 커맨드

시스템 프롬프트에 "user-invocable skills" 로 등록된 스킬은 사용자가 /name 형태로 직접 호출할 수 있다. 이 저장소의 aptabase 스킬도 /aptabase 로 호출 가능하다.

Claude 입장에서는:

사용자가 /aptabase 를 입력 → Skill 툴을 통해 해당 스킬을 명시적으로 로드
자동 매칭보다 우선순위가 높음
이미 로드된 스킬을 또 호출하지 않음

6. 스킬 vs 훅 vs 메모리 — 구분

혼동하기 쉬운 세 가지 퍼시스턴스 메커니즘:

구분	저장 위치	트리거	목적
Skill	`.claude/skills/<name>/SKILL.md`	description 매칭 또는 `/name`	작업 절차/도메인 지식 — Claude 가 어떤 일을 어떻게 해야 하는지
Hook	`.claude/settings.json` + 스크립트	특정 이벤트 (Stop, PostToolUse 등)	자동 실행 — Claude 와 무관하게 이벤트 발생 시 시스템이 스크립트 구동
Memory	`~/.claude/projects/.../memory/`	관련성 / 명시 요청	지속 기억 — 사용자·프로젝트·피드백·외부 참조 정보

aptabase 는 스킬(운영 가이드) + 훅(자동 기록 실행) 의 조합으로 동작한다. 스킬은 "Claude 가 사람처럼 절차를 따라야 할 때" 읽는 문서이고, 훅은 "시스템이 이벤트마다 기계적으로 실행" 하는 스크립트다. 서로 교체 불가능하며 상호보완적이다.

7. 참고

현재 이 저장소의 스킬 구성은 .claude/skills/aptabase/SKILL.md 한 개만 있다.
전역 스킬(다른 프로젝트에서도 쓰는 것) 은 ~/.claude/skills/ 또는 플러그인(ouroboros:* 등)으로 제공된다.
Aptabase 훅 자체의 상세 구현/설정은 .claude/hooks/usage.md 를 참조.

7.1 KiB Raw Permalink Blame History