2 added, 2 removed. Audit A to A.
# AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository.
---
## [Docs Index]|root: ./
|IMPORTANT: Prefer retrieval-led reasoning over pre-training knowledge
|skills/:{ai-tools,meta,documentation,frontend,development,planning,professional,testing,git,utilities}
|agents/:{fullstack,ai-ml,api,qa,docs,design,migration,planning,communication,general}
### Quick Retrieval Paths
|Task|Read First|
|---|---|
|AI/LLM API 코딩|프로젝트 SDK·lockfile·기존 추상화·평가 테스트 우선; 공급자 공식 문서 확인, OpenAI는 openai-docs 사용|
|React/Next.js|프로젝트 manifest·lockfile·tsconfig·기존 구조·테스트 우선; 버전 API는 공식 문서 확인|
|Code Review|skills/code-reviewer/SKILL.md|
|Docker Deploy|skills/docker-deploy/SKILL.md,skills/docker-deploy/templates/|
|Docker DB Backup|skills/docker-db-backup/SKILL.md|
|API Testing|skills/api-tester/SKILL.md|
|Documentation|네이티브 작성 + 목적별 skills/api-handoff, documentation-and-adrs, release-notes, crafting-effective-readmes|
|FastAPI|프로젝트·공식 문서 우선; 명시 요청 시 skills/python-backend-fastapi/SKILL.md|
|Spring Boot|프로젝트 build manifest·BOM·기존 계층·설정·테스트 우선; 버전 API는 공식 문서 확인|
|ASP.NET Core|프로젝트·공식 문서 우선; agents/backend-dotnet.md는 소스 참고용|
|WPF Desktop|프로젝트·공식 문서 우선; agents/desktop-wpf.md는 소스 참고용|
|Database Design|skills/database-schema-designer/SKILL.md|
|Database (MySQL)|프로젝트 DB 버전·schema·migration 도구·실행 계획 우선|
|Database (PostgreSQL/Supabase)|프로젝트 schema·RLS·연결 설정 우선; 명시 요청 시 skills/supabase-postgres-best-practices/SKILL.md|
|Migration|네이티브 코드 탐색 후 skills/deprecation-and-migration/SKILL.md|
|Naming|명시 요청 시 skills/naming-analyzer/SKILL.md|
|Architecture|네이티브 계획·검토 + skills/documentation-and-adrs/SKILL.md; 필요 시 mermaid-diagrams|
|SPEC Interview|skills/zephermine/SKILL.md|
|Security Review|skills/code-reviewer/SKILL.md,skills/code-reviewer/references/security-audit.md|
|Web Preview + 디자인 토큰|DESIGN.md 우선; 명시 요청 시 skills/design-system-starter/SKILL.md|
|Stitch UI|skills/stitch/SKILL.md|
|Agent Teams (4-CLI 네이티브 병렬 실행)|skills/agent-team/SKILL.md|
|Codex Multi-Agent Team|skills/agent-team-codex/SKILL.md|
### Recommended Workflows
|시나리오|체이닝 순서|
|---|---|
|새 프로젝트 (풀코스)|zephermine → 네이티브 아키텍처 검토/ADR → agent-team → minos → docker-deploy|
|전자동 (제우스)|zeus — 한 줄 설명만으로 설계→구현→테스트 완전 자동|
|기능 추가|zephermine → agent-team/수동 구현 → minos|
|데이터 설계|domain expert → database-schema-designer → 네이티브 DB별 구현·migration 테스트|
|UI 와이어프레임|aphrodite --plan-only (벤치마크 분석 → Experience Contract → 렌더 방향 비교); 원격 화면이 필요할 때만 `aphrodite --stitch`|
|UI 디자인 → 구현|aphrodite가 source-only frontend-design·감사 모듈을 직접 읽고 네이티브 구현; 명시 시 Stitch 어댑터 사용|
|코드 리뷰 종합|CLI 네이티브 review → code-reviewer 정책 레이어|
|코드 정리|hestia (dead code 탐지 + 삭제)|
|리팩토링|네이티브 코드 탐색 → deprecation-and-migration → code-reviewer|
|보안 감사|code-reviewer 보안 감사 모드 → 필요 시 argos Phase 7|
|UI/UX 품질 점검|design-plan이 렌더 비평과 source-only ui-ux-auditor 기준을 직접 적용|
|QA 자동화|minos (시나리오 자동 생성 → Playwright → Healer)|
|반복 수정 루프|auto-continue-loop (이슈 탐색 → 수정 → 검증 → 다음, 자동 반복)|
|다이어그램 기반 구현 검증|flow-verifier plan → 구현 → flow-verifier verify (코드 흐름 ↔ 다이어그램 대조)|
> 상세 가이드: [docs/workflow-guide.md](docs/workflow-guide.md)
---
## Core Rules (Always Apply)
|Rule|Principle|Action|
|---|---|---|
|Single responsibility|1 file = 1 role|Split by responsibility|
|No circular deps|Unidirectional|Restructure dependency direction|
|Security|OWASP Top 10|Check SQL injection, XSS, CSRF|
|Type safety|Required|Add type hints (Python) / TypeScript|
|DRY principle|No duplication|Extract reusable components|
## Native-First 구현 경계 (항상 적용)
- 일반 구현은 네이티브 코딩 능력과 프로젝트 코드·테스트·규칙을 먼저 따르고, 범용 코딩 표준 스킬은 사용자가 명시적으로 호출할 때만 사용한다.
- 기존 구조와 기존 composition point를 우선하며, 같은 역할의 새 계층이나 병렬 구조를 만들지 않는다.
- 독립적으로 변경·테스트되는 책임만 모듈로 분리하고, 모듈은 내부를 숨긴 채 명시적 계약(interface/type/function)만 노출한다.
- 모듈 간 순서·분기·조합은 기존 Application/Service/Composition Root 같은 하네스가 담당하고, 모듈끼리는 구현이 아니라 계약에만 의존한다.
- 이 규칙은 두 개 이상의 독립 블록이 있거나 독립 변경 필요가 확인될 때만 적용한다. 단순 작업에는 새 인터페이스·레이어·하네스를 추가하지 않는다.
- 네이티브 역할은 읽기 전용 탐색(Claude `Explore`, Codex `explorer`, Gemini `codebase_investigator`, Grok `explore`)과 쓰기·실행 작업(Claude `general-purpose`, Codex `worker`, Gemini `generalist`, Grok `general-purpose`)으로 분리한다. 읽기 전용 역할에 파일 쓰기를 맡기지 않는다.
- 메인 컨텍스트가 공유 태스크 장부·활동 로그·완료 판정을 소유하고, 작업자는 고유 파일을 맡거나 결과만 반환한다. 위임이 없거나 병렬 이득이 없으면 메인 컨텍스트에서 순차 실행한다.
- 기본 활성 스킬은 사용자 진입점 하네스다. 하네스가 source-only 하위 모듈을 필요로 하면 그 스킬을 호출하지 말고 카탈로그의 정확한 `SKILL.md`를 직접 읽는다. 참조와 실행 파일은 해석된 모듈 디렉터리를 기준으로 찾으며, 필수 모듈 누락은 실패 또는 `NOT RUN`으로 남기고 누락을 `PASS`로 처리하지 않는다.
---
## Cross-CLI Compatibility
- Claude Code에서 제공하는 skills, agents, hooks, MCP 기능은 Codex에서도 동일 기능 parity를 목표로 유지합니다.
- 기본 활성 사용자 호출명은 CLI 간에 동일하게 유지합니다. Claude에서 `/themis`, `workpm`, `agent-team`으로 호출되면 Codex에서도 같은 이름으로 접근 가능해야 합니다. source-only 스킬의 slash 호출은 `--include-source-only-skills`로 활성화한 뒤에만 같은 보장을 적용합니다.
- 내부 구현은 CLI별 실행 모델 차이를 반영해 달라질 수 있지만, 사용자 인터페이스와 핵심 결과는 맞춰야 합니다.
- 단순 파일 복사만으로 parity를 판단하지 말고, 전역 설치본에서 실제로 동작하는지까지 검증합니다.
- Codex 스킬은 기본적으로 `~/.codex/skills/`에만 설치합니다. 이 저장소의 `.agents/skills` 미러는 격리 테스트용 `--include-project-skills` 옵션에서만 생성합니다.
- 공개 추적 스킬 소스 99개는 기본 allowlist 합집합 17개(공통 진입점 하네스 11개 + 런타임 어댑터 6개)와 source-only 내부·선택 모듈 82개로 나눕니다. 호환되지 않는 어댑터를 제외하면 Claude는 96개(활성 14 + source-only 82), Codex와 Gemini는 각각 95개(활성 13 + source-only 82)입니다. Grok 논리 정책도 95개지만 실제 설치 표면은 Claude 공유 디렉터리를 읽어 활성 14개를 봅니다. 내부 전용 `deploymonitor`는 로컬에만 있어 공개 배포 수에 포함하지 않습니다. 새 스킬은 allowlist 승인 전까지 자동 활성화하지 않습니다. 전체 복원은 `--include-source-only-skills`, 구 코딩 가이드 8개만 복원은 `--include-broad-coding-skills`를 사용합니다.
- 스킬 문서의 `skills/{name}/...` 경로는 현재 프로젝트에 실제 파일이 없으면 현재 CLI의 활성 스킬 루트, 이어서 `SKILLS-CATALOG.md`의 source-only `읽을 경로`를 기준으로 절대경로를 해석합니다. 활성 하네스가 source-only 모듈에 의존할 때는 `/name` 호출 대신 정확한 원본을 직접 읽고, 참조·스크립트는 해석된 모듈 루트를 기준으로 실행합니다.
- 사용자 정의 에이전트는 기본 거부 정책으로 0개를 등록합니다. 현재 소스 42종(패시브 9, 네이티브 중복 7, 중복 전문·스킬 래퍼 24, 워크플로 호환 프롬프트 2)은 source-only이며, 새 에이전트도 고유 런타임 계약을 입증해 allowlist에 넣기 전에는 자동 활성화되지 않습니다. 전체 소스 복사가 필요할 때만 `--include-source-only-agents`를 사용하고, Codex 프로젝트 에이전트 미러는 `--include-project-agents`에서만 생성합니다.
- 우선 고정 호출명: `/zephermine`(젭마인), `/zeus`(제우스), `/aphrodite`(아프로디테), `workpm`/`/daedalus`(다이달로스), `/chronos`(크로노스), `/minos`(미노스), `/agent-team`(`/poseidon`, 포세이돈), `/argos`(아르고스), `/clio`(클리오), `/themis`(테미스), `/hermes`(헤르메스), `/athena`(아테나), `/mnemo`(므네모)
---
### Web Preview Mode Development Guide
웹 프리뷰 모드(채팅 모드 + dev server + PreviewPanel)에서는 **경험 계약 → 디자인 시스템 → Frontend → Backend** 순서를 따릅니다.
|Phase|핵심|
|---|---|
|Phase 0: Experience + Design DNA|과업·메시지·CTA·신뢰·모바일 변환 → 벤치마크 판정 → 렌더 방향 비교 → 토큰 확정|
|Phase 1: Frontend → Backend|Experience Contract 기반 UI·상태 구현 → API·비즈니스 로직 연결 (프리뷰 패널 실시간 확인)|
|Phase 2: Pre-Delivery|실제 렌더 미학, 과업, 접근성, 반응형, 성능 최종 검증|
> **본격 디자인 작업**: `/aphrodite` 또는 `design-plan` 스킬을 명시 호출합니다.
---
## Repository Overview
A comprehensive collection of skills and agents for Claude Code and other AI coding agents. Extends agent capabilities across development, documentation, planning, and professional workflows.
## Available Resources
- ### Skill sources (공개 추적 99개; 기본 allowlist 합집합 17개, 런타임별 활성 13개 또는 14개)
+ ### Skill sources (공개 추적 100개; 기본 allowlist 합집합 17개, 런타임별 활성 13개 또는 14개)
| 카테고리 | 스킬 | 설명 |
|----------|------|------|
| 🤖 AI Tools | codex, gemini, orchestrator, workpm (다이달로스), agent-team, agent-team-codex | 외부 AI 모델 연동 + 멀티 AI 오케스트레이션 + 다이달로스(현장감독) PM + 4-CLI 네이티브 멀티에이전트 (orchestrator MCP는 폴백) + Codex Multi-Agent |
| 🔮 Meta | agent-md-refactor, autoresearch, command-creator, plugin-forge, skill-judge, find-skills, manage-skills, project-gotchas, memory-distill, skill-evolve, verify-implementation | 플러그인/스킬 생성/검색/검증 + 오답노트 자동 관리 + raw 관찰 정제(rebuild) + 스킬 프롬프트 자동 최적화 (Hill Climbing) + gotcha/learned 기반 스킬 자기개선 루프 |
- | 📝 Documentation | api-handoff, crafting-effective-readmes, domain-dictionary, draw-io, excalidraw, marp-slide, mermaid-diagrams, writing-clearly-and-concisely, docx, pdf, excel2md | 문서/다이어그램 + 도메인 용어사전 (DDD Ubiquitous Language) + Office 문서 읽기/생성/편집 (Word/PDF/Excel) |
+ | 📝 Documentation | api-handoff, crafting-effective-readmes, diagram-design, domain-dictionary, draw-io, excalidraw, marp-slide, mermaid-diagrams, writing-clearly-and-concisely, docx, pdf, excel2md | 문서/다이어그램 + 에디토리얼 다이어그램 렌더링(.mmd → 브랜드 HTML+SVG 표현 계층) + 도메인 용어사전 (DDD Ubiquitous Language) + Office 문서 읽기/생성/편집 (Word/PDF/Excel) |
| 📖 Learning | explain | 코드 설명 (비유 + Mermaid) + 줌아웃 모드 (호출자/형제/상위 맵) |
| 🎨 Frontend | design-plan (아프로디테), frontend-design, design-system-starter, theme-factory, mui, openapi-to-typescript, react-dev, vercel-react-best-practices, stitch, seo-audit, ui-ux-auditor, data-visualization | 사이트 벤치마크·Experience Contract·실제 렌더 3안·UX/접근성/성능 게이트를 지휘하는 디자인 오케스트레이터 + React/TypeScript/디자인/Stitch UI 생성 + 테마·SEO·UI/UX 감사 + 차트 선택 가이드 |
| 🛠️ Development | database-schema-designer, supabase-postgres-best-practices, dependency-updater, deprecation-and-migration, docker-deploy, docker-db-backup, deploymonitor, wrangler, documentation-and-adrs, fullstack-coding-standards, dotnet-coding-standards, wpf-coding-standards, hestia (헤스티아), naming-analyzer, python-backend-fastapi, social-login, health-data | 개발 도구 + Postgres 최적화 + Cloudflare Workers 배포 + 헬스 데이터(Health Connect/HealthKit) 연동 |
| 🎯 Planning | game-changing-features, shipping-and-launch, zeus (제우스), zephermine (젭마인), ship-learn-next | 계획/요구사항 |
| 👔 Professional | daily-meeting-update, workplace-conversations, professional-communication | 비즈니스 커뮤니케이션 |
| 🧪 Testing | code-reviewer, minos, auto-continue-loop, flow-verifier, argos (아르고스), clio (클리오), themis (테미스), api-tester, test-driven-development, systematic-debugging, semgrep-rule-creator | 테스트/리뷰/자동 수정 루프/플로우 검증/감리(준공검사)/최종 점검+산출물 + 개인정보 전수 감사→국가별 처리방침 생성(ko/us/eu) + API 연동 테스트 + TDD 사이클 + 근본원인 디버깅 + Semgrep 커스텀 규칙 |
| 📦 Git | commit-work, release-notes | Git 워크플로우 & 릴리즈 노트 자동화 (버전+CHANGELOG+태그) |
| 💰 Estimation | estimate | 개발 견적서 자동 생성 (비용 그룹별 공수 산정 → 엑셀 출력) |
| 📈 Business | biz-strategy (헤르메스), ceo (아테나), okr | 사업성 검토, CEO 코칭 (Go/No-Go), OKR 목표 관리 |
| 🎬 Media | video-maker | Remotion(React/TSX)·HyperFrames(HTML/CSS/GSAP) 선택형 코드 영상 제작. 전역 설치·동기화 없이 프로젝트 엔진 하나만 사용 |
| 🌐 Translation | ko-en-translator | 한국어↔영어 양방향 번역 (텍스트, 기술 문서, 코드 주석, i18n 파일, 커밋 메시지) |
| 🔧 Utilities | datadog-cli, domain-name-brainstormer, humanizer, jira, meme-factory, ppt-generator, web-design-guidelines, web-to-markdown, youtube-transcript | 유틸리티 + YouTube 자막 추출/요약 |
| 📊 Research | reddit-researcher | Reddit 시장 조사 + 리드 스코어링 + Pain Point 분류 |
| 🧠 Memory/Session | mnemo, codex-mnemo, gemini-mnemo, grok-mnemo, memory-compact | 기억 시스템 (대화 저장 + 태깅 + 검색 + MEMORY.md + 세션 핸드오프) + CLI별 어댑터 (Codex notify / Gemini AfterAgent / Grok camelCase envelope) + 메모리 크기 점검 및 압축 |
### Agents (참고 소스 42개: 최상위 40개 + 스킬 소유 2개, 기본 등록 0개)
| 카테고리 | 에이전트 | 설명 |
|----------|----------|------|
| **Optional References** | architect | 네이티브 계획·검토와 documentation-and-adrs로 대체된 아키텍처 참고자료 (소스 보존, 기본 미설치) |
| | documentation | 네이티브 작성과 목적별 문서 스킬로 대체된 템플릿 참고자료 (소스 보존, 기본 미설치) |
| | mermaid-diagram-specialist | mermaid-diagrams 스킬로 대체된 다이어그램 참고자료 (소스 보존, 기본 미설치) |
| | typescript-spec | 프로젝트 설정·컴파일러를 따르는 네이티브 TypeScript 작업으로 대체 (소스 보존, 기본 미설치) |
| | python-spec | 프로젝트 설정·테스트를 따르는 네이티브 Python 작업으로 대체 (소스 보존, 기본 미설치) |
| | ui-ux-designer | design-plan 렌더 비평과 ui-ux-auditor로 대체 (소스 보존, 기본 미설치) |
| | frontend-react | 프로젝트 manifest·기존 UI 구조·테스트를 따르는 네이티브 구현으로 대체 (소스 보존, 기본 미설치) |
| | backend-spring | 프로젝트 build manifest·기존 계층·테스트를 따르는 네이티브 구현으로 대체 (소스 보존, 기본 미설치) |
| | database-mysql | 프로젝트 DB 버전·schema·migration·실행 계획 기반 구현으로 대체 (소스 보존, 기본 미설치) |
| | database-postgresql | 프로젝트 schema·RLS·연결 설정과 명시형 Postgres 스킬로 대체 (소스 보존, 기본 미설치) |
| | react-best-practices | React/Next.js 최적화 참고 문서 (소스 보존, 기본 미설치) |
| | python-fastapi-guidelines | FastAPI 참고 문서 (소스 보존, 기본 미설치) |
| | fullstack-coding-standards | 풀스택 참고 표준 (소스 보존, 기본 미설치) |
| | dotnet-coding-standards | .NET 참고 표준 (소스 보존, 기본 미설치) |
| | wpf-coding-standards | WPF 참고 표준 (소스 보존, 기본 미설치) |
| | naming-conventions | 네이밍 참고 문서 (소스 보존, 기본 미설치) |
| | writing-guidelines | 글쓰기 + AI 패턴 제거 참고 문서 (소스 보존, 기본 미설치) |
| | bilingual-dev | 한↔영 개발 참고 문서 (소스 보존, 기본 미설치) |
| | web-preview-guide | 레거시 웹 프리뷰 상세 문서 (소스 보존, 기본 미설치) |
| | codebase-pattern-finder | 네이티브 탐색과 중복되는 패턴 검색 참고자료 (소스 보존, 기본 미설치) |
| | explore-agent | 네이티브 탐색과 중복되는 레거시 분석 참고자료 (소스 보존, 기본 미설치) |
| | debugger | 네이티브 진단과 중복되는 디버깅 참고자료 (소스 보존, 기본 미설치) |
| | feature-tracker | 네이티브 계획 상태·핸드오프로 대체된 추적 참고자료 (소스 보존, 기본 미설치) |
| | tdd-coach | 네이티브 테스트 루프와 명시형 TDD 스킬로 대체 (소스 보존, 기본 미설치) |
| | migration-helper | deprecation-and-migration으로 대체된 참고자료 (소스 보존, 기본 미설치) |
| | spec-interviewer | zephermine 인터뷰 흐름으로 대체된 참고자료 (소스 보존, 기본 미설치) |
| | api-comparator | 네이티브 diff + deprecation-and-migration + api-tester로 대체 (소스 보존, 기본 미설치) |
| | api-tester | 동명 api-tester 스킬로 대체 (소스 보존, 기본 미설치) |
| | ascii-ui-mockup-generator | 네이티브 ASCII 출력과 Aphrodite 와이어프레임 흐름으로 대체 (소스 보존, 기본 미설치) |
| | backend-dotnet | 프로젝트·공식 문서 우선의 ASP.NET Core 참고자료 (소스 보존, 기본 미설치) |
| | database-schema-designer | 동명 database-schema-designer 스킬로 대체 (소스 보존, 기본 미설치) |
| | desktop-wpf | 프로젝트·공식 문서 우선의 WPF 참고자료 (소스 보존, 기본 미설치) |
| | performance-engineer | 네이티브 측정·프로파일링을 우선하는 성능 참고자료 (소스 보존, 기본 미설치) |
| | stitch-developer | stitch 스킬로 대체된 얇은 호스트 (소스 보존, 기본 미설치) |
| | writing-specialist | 네이티브 글쓰기와 명시형 글쓰기 스킬로 대체 (소스 보존, 기본 미설치) |
| | ai-ml | 정적 공급자 API·RAG 참고자료; 실제 구현은 프로젝트 SDK·공식 문서·평가 테스트 우선 (소스 보존, 기본 미설치) |
| | qa-engineer | Minos·Argos·실제 테스트 실행으로 대체된 QA 참고자료 (소스 보존, 기본 미설치) |
| | qa-writer | Zephermine·Minos의 시나리오 생성 계약으로 대체된 참고자료 (소스 보존, 기본 미설치) |
| | code-reviewer | 동명 스킬과 CLI 네이티브 리뷰로 대체된 얇은 래퍼 (소스 보존, 기본 미설치) |
| | security-reviewer | 안전한 보안 감사 참조와 Argos Phase 7로 흡수된 정적 감사 프롬프트 (소스 보존, 기본 미설치) |
| **Skill-owned source-only** | chronos-worker | auto-continue-loop 정본을 가리키는 선택 호환 프롬프트 (기본 미설치) |
| | gotcha-analyzer | memory-distill 정본을 가리키는 선택 호환 프롬프트 (기본 미설치) |
## Creating a New Skill
### Directory Structure
```
skills/
{skill-name}/ # kebab-case directory name
SKILL.md # Required: skill definition
scripts/ # Required: executable scripts
{script-name}.sh # Bash scripts (preferred)
{skill-name}.zip # Required: packaged for distribution
```
### Naming Conventions
- **Skill directory**: `kebab-case` (e.g., `vercel-deploy`, `log-monitor`)
- **SKILL.md**: Always uppercase, always this exact filename
- **Scripts**: `kebab-case.sh` (e.g., `deploy.sh`, `fetch-logs.sh`)
- **Zip file**: Must match directory name exactly: `{skill-name}.zip`
### SKILL.md Format
```markdown
---
name: {skill-name}
description: {One sentence describing when to use this skill. Include trigger phrases like "Deploy my app", "Check logs", etc.}
---
# {Skill Title}
{Brief description of what the skill does.}
## How It Works
{Numbered list explaining the skill's workflow}
## Usage
```bash
bash /mnt/skills/user/{skill-name}/scripts/{script}.sh [args]
```
**Arguments:**
- `arg1` - Description (defaults to X)
**Examples:**
{Show 2-3 common usage patterns}
## Output
{Show example output users will see}
## Present Results to User
{Template for how Claude should format results when presenting to users}
## Troubleshooting
{Common issues and solutions, especially network/permissions errors}
```
### Best Practices for Context Efficiency
Skills are loaded on-demand — only the skill name and description are loaded at startup. The full `SKILL.md` loads into context only when the agent decides the skill is relevant. To minimize context usage:
- **Keep SKILL.md concise** — put detailed reference material in separate files (progressive disclosure)
- **Write short, routing-focused descriptions** — include trigger words and boundaries; put workflow details in the body
- **Use progressive disclosure** — reference supporting files that get read only when needed
- **Prefer scripts over inline code** — script execution doesn't consume context (only output does)
- **File references work one level deep** — link directly from SKILL.md to supporting files
### Script Requirements
- Use `#!/bin/bash` shebang
- Use `set -e` for fail-fast behavior
- Write status messages to stderr: `echo "Message" >&2`
- Write machine-readable output (JSON) to stdout
- Include a cleanup trap for temp files
- Reference the script path as `/mnt/skills/user/{skill-name}/scripts/{script}.sh`
### Creating the Zip Package
After creating or updating a skill:
```bash
cd skills
zip -r {skill-name}.zip {skill-name}/
```
### End-User Installation
Document these two installation methods for users:
**Claude Code:**
```bash
cp -r skills/{skill-name} ~/.claude/skills/
```
**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.
If the skill requires network access, instruct users to add required domains at `claude.ai/settings/capabilities`.
---
## Skills vs Agents: When to Use
Based on [Vercel's agent evaluation research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):
|Use Case|Recommended|Reason|
|---|---|---|
|Framework knowledge|AGENTS.md|Passive context = 100% pass rate|
|Code generation rules|AGENTS.md|Always available, no decision point|
|User-triggered workflows|Skills|기본 활성 진입점은 명시 호출; source-only는 자연어 요청으로 카탈로그 직접 로드|
|Version migrations|Skills|One-time, explicit action|
|Architecture changes|Skills|Requires user confirmation|
### Key Insight
> **Retrieval-led reasoning > Pre-training knowledge**
>
> When documentation exists in this repo, READ IT before relying on training data.
> Training data may be outdated; local docs are authoritative.
---
## Hooks (Automatic Enforcement)
훅은 특정 이벤트에서 자동 실행되어 규칙을 강제합니다.
### Available Hooks
|훅|타이밍|트리거|동작|
|---|---|---|---|
|check-new-file.sh|PreToolUse|새 파일 생성|유사 파일 경고|
|protect-files.sh|PreToolUse|민감 파일 수정|.env, credentials 보호|
|validate-api.sh|PostToolUse|API 파일 수정|구문/타입 검사|
|save-conversation.sh|UserPromptSubmit|모든 입력|사용자 입력을 대화 파일에 저장|
|save-response.sh|Stop|세션 종료|Assistant 응답을 대화 파일에 저장|
|save-tool-use.sh|PostToolUse|도구 실행|도구 사용 로그 + gotchas/learned 관찰 저장|
|reconcile-conversations.sh|SessionStart|세션 시작|Claude transcript + Codex rollout JSONL 기준으로 save-response/save-turn이 놓친 턴을 backfill (멱등)|
|orchestrator-detector.js|UserPromptSubmit|workpm/pmworker 입력|PM/Worker 모드 감지|
|loop-stop.sh|Stop|Chronos 루프 활성 시|세션 종료 가로채서 프롬프트 재투입 (자동 반복)|
### 3-Layer Architecture
```
Layer 1: AGENTS.md (Passive Guidelines)
→ 핵심 규칙이 항상 컨텍스트에 존재
→ AI가 처음부터 좋은 코드 작성
Layer 2: Hooks (Automatic Enforcement)
→ 규칙 위반 자동 감지
→ 즉시 피드백
Layer 3: Skills (On-demand Analysis)
→ 기본 활성 하네스는 slash/별칭으로 진입
→ source-only 분석 모듈은 자연어 요청 시 카탈로그 원본 직접 로드
```
### Hook Configuration (settings.json)
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": ["bash hooks/check-new-file.sh"]
},
{
"matcher": "Edit|Write",
"hooks": ["bash hooks/protect-files.sh"]
}
],
"PostToolUse": []
}
}
```
<!-- CODEMAP_RULES_START -->
## Code Map (자동 생성)
> 이 섹션은 TermSnap CodeMapService가 자동 관리합니다. 수동 편집하지 마세요.
코드 위치를 찾을 때 다음 순서로 진행하세요. 앞 단계에서 충분한 정보를 얻으면 다음 단계는 건너뜁니다.
1. **`codemap/index.md`** — 카테고리 + 파일 수 요약. 필요하면 `codemap/info.md`의 작업별 라우터로 읽는 순서를 확인.
2. **해당 카테고리 `.md` grep** — 통째 read 금지. 항목 옆 `(L123)` 라인 번호는 그대로 `Read(file, offset=L, limit=N)` 사용.
3. **검색 결과가 많으면 로컬 압축 우선** — `rg --json`/`rg --vimgrep`/`file:line:text` 결과를 파일별로 묶고 routes/api/ui 신호와 source/test/document 가중치로 상위 파일만 읽음. MCP `codemap_compress_search`는 외부 agent용 선택 경로이며 필수 단계가 아님.
4. **못 찾으면 일반 grep/Glob** — codemap이 stale일 수 있음. 의심되면 사용자에게 "코드맵 갱신"을 권장.
코드 위치 답변 시 `file:line` 형식 사용 (예: `RAGService.cs:53`).
<!-- CODEMAP_RULES_END -->