doksam-skills: Instructions file for Codex

doksam-skills - AI Agent Guidelines

이 문서는 AI 에이전트(Gemini, Claude 등)가 이 저장소(Repository)에서 작업할 때 지켜야 할 규칙과 프로젝트 컨텍스트를 정의합니다. GEMINI.md, CLAUDE.md 등에서 이 파일을 참조합니다.

1장~3장은 스킬 개수와 무관한 저장소 공통 규약이고, 4장부터는 스킬별 작업 지침입니다.

1. 프로젝트 개요 (Project Context)

• 성격: 이 저장소는 Agent Skill 모음(doksam-skills)입니다. skills/ 아래 스킬 하나가 배포 단위이며, install.sh 가 전부를 Claude Code / Codex / Antigravity 경로에 심링크로 노출합니다.
• 소유 원칙: 스킬 하나가 자기 자산을 전부 소유합니다. 행동 계약(SKILL.md), 리소스, 스크립트, 테스트, 세 런타임 Agent Adapter 가 모두 skills/<skill>/ 안에 있습니다. 저장소 루트에는 설치기와 공통 규약 검증만 둡니다. 특정 스킬에만 쓰이는 파일을 루트 scripts/ 나 tests/ 에 두지 않습니다.
• 기술 스택: 스킬 정의는 Markdown, 템플릿은 HTML5 + Vanilla CSS, 검증/테스트 스크립트는 Python 3 stdlib 와 bash 입니다.
• 언어 정책 (한국어 우선): 이 저장소는 한국인 사용자를 위한 스킬 모음입니다. SKILL.md 본문·frontmatter description·Agent Adapter·문서·커밋/이슈/PR 본문은 한국어로 작성합니다. 단, 영어가 더 정확하거나 필수인 것은 영어를 유지합니다 — 코드 식별자·클래스명·명령어·파일/키 이름(name, description 키 등), 고유 기술용어(IA, Storyboard, SSOT, frontmatter 등), 외부 도구가 요구하는 형식. 트리거 매칭에 쓰이는 description 은 한국어 문장으로 쓰되 핵심 키워드는 한/영을 병기할 수 있습니다.

2. 스킬 레이아웃 규약

skills/<skill>/
  SKILL.md            필수. frontmatter 는 name·description 두 개뿐이고 name 은 디렉터리명과 같다
  agents/             선택. 아래 파일명만 허용한다
    claude.md         Claude Code Agent Adapter
    codex.toml        Codex custom agent (name 은 스킬명의 - 를 _ 로 바꾼 것)
    antigravity.md    Gemini API Managed Agent 등록용 역할 정의 원본
    openai.yaml       Codex UI 용 스킬 메타데이터
  resources/          템플릿 등
  scripts/            이 스킬 전용 스크립트
  tests/              이 스킬 전용 테스트

루트 .claude/agents/<skill>.md 와 .codex/agents/<skill_>.toml 은 위 원본을 가리키는 심링크입니다. 원본을 그 자리에 직접 두지 않습니다.

Agent Adapter 에 스킬의 행동 규칙을 복제하지 않습니다. 공통 행동 계약은 SKILL.md 한 곳에서 관리하고 Adapter 는 역할·호출·완료 조건만 정의합니다.

claude.md 와 antigravity.md 는 YAML frontmatter(name·description)가 필수입니다. 특히 agy 는 frontmatter 가 없는 agent md 를 오류도 경고도 없이 무시합니다 — 플러그인에는 파일이 복사돼 있는데 agy agents 에는 안 나오는 상태가 됩니다 (2026-08-11 agy 1.1.11 실측, 이슈 #110). 등록 여부는 파일 존재가 아니라 agy agents 출력으로 확인하세요.