프런트매터 스키마
아티팩트 클래스 전반의 YAML 프런트매터 블록 구조, 클래스별 필수 키, 검증기 강제 규칙에 관한 참조 가이드입니다.
모든 아티팩트 클래스의 YAML 프런트매터에 관한 정식 참조.
CLAUDE.md의 Conventions에 있는 요약은 인라인 선언이며,src/apothem/schemas/의 클래스별 JSON 스키마(스킬과 명령 스키마의additionalProperties: false는 알 수 없는 키를 거부하고, 에이전트, 출력 스타일, 플랜 스키마는additionalProperties: true로 설정됨)가 기계가 읽을 수 있는 계약이며 불일치가 있으면 항상 우선합니다. 이 페이지는 필수 키 색인이고,artifact-schema.mdx는 클래스별 템플릿과 상세 예시를 담습니다. 두 문서 모두 이 스키마들을 사람이 읽을 수 있게 투영한 것입니다.
1. 프런트매터 블록 형태
모든 아티팩트는 맨 앞에 --- 줄로 구분된 YAML 프런트매터를 둡니다. Markdown 계열 파일에서는 프런트매터가 파일의 첫 번째 콘텐츠이고, site/content/docs/reference/authorship-header.mdx에 따른 정식 SPDX 헤더 줄은 닫는 --- 뒤에 옵니다.
커맨드 키는 kebab-case를 사용합니다. 스킬 키는 kebab-case를 사용하되, 소스 코퍼스가 쓰는 camelCase 표기인 userInvocable만 예외입니다(Claude Code 설치는 이를 user-invocable로 이름 바꿉니다). Claude Code 설치와 플러그인은 또한 스킬이나 커맨드의 Apothem 전용 키(version, updated, archetype, portability)를 따옴표로 묶은 문자열로 이루어진 후행 metadata: 맵 아래로 이 고정된 순서대로 옮깁니다. Claude Code는 알 수 없는 최상위 키를 무시하고, Agent Skills 표준은 추가 키를 metadata에 두기 때문입니다. 소스 파일과 다른 모든 하니스는 이 키들을 최상위에 유지하지만, 공유 사용자 수준 스킬 폴더(~/.agents/skills/와 ~/.codebuddy/skills/, ~/.kiro/skills/, ~/.trae/skills/ 폴더)는 예외로 같은 방식으로 접어 넣습니다. 규칙과 위임 작업자의 키는 섹션 2의 필수 키 표에 나열된 대로 camelCase입니다. 스칼라 값은 따옴표 없이 쓰거나 큰따옴표로 묶으며, 콜론, 해시 기호 또는 그 밖의 YAML에서 의미를 갖는 문자가 들어 있는 문자열 값은 따옴표로 묶습니다.
2. 클래스별 필수 필드
필수 키 집합은 아티팩트 클래스에 따라 다릅니다. 권위 있는 형태는 scripts/dev/validate_ecosystem.py와 src/apothem/schemas/ 디렉터리 아래의 클래스별 JSON 스키마가 강제합니다. 헬퍼, 스킬, 명령, 출력 스타일, 플랜 클래스에는 각각 스키마 파일이 하나씩 있으며 아래에 나열되어 있습니다. CLAUDE.md와 규칙 클래스에는 스키마 파일이 없으며, validate_ecosystem.py가 이들의 키를 검사합니다. 플랜 파일은 아래 표에 없으며, 플랜 파일의 키는 계획 디시플린에 나열되어 있습니다.
src/apothem/schemas/agent.schema.json
src/apothem/schemas/skill.schema.json
src/apothem/schemas/command.schema.json
src/apothem/schemas/output-style.schema.json
src/apothem/schemas/plan.schema.json| 클래스 | 필수 키 |
|---|---|
CLAUDE.md(루트 구성) | name, version, updated, description, scope, portability |
규칙(src/apothem/rules/*.md) | name, description, pathFilter, alwaysApply |
명령(src/apothem/commands/*.md) | name, version, updated, description, argument-hint, disable-model-invocation, portability, allowed-tools |
헬퍼, 위임 작업자라고도 함(src/apothem/agents/*.md) | name, version, updated, description, tools(선택 사항: 이를 생략한 헬퍼는 모든 도구를 상속합니다. tools를 나열하는 헬퍼에 MCP 서버를 부여하려면 프로필의 agent_mcp_servers 키에 해당 서버를 지정하세요), disallowedTools, maxTurns, effort |
스킬(src/apothem/skills/*/SKILL.md) | name, version, updated, description, archetype, userInvocable, disable-model-invocation, allowed-tools. Claude Code 설치와 플러그인, 그리고 공유 사용자 수준 스킬 폴더는 userInvocable을 user-invocable로 이름을 바꾸며, 스키마는 각 스킬이 두 표기 중 정확히 하나만 갖도록 요구하고 둘 다 갖는 것은 허용하지 않습니다. Qwen Code 설치는 allowed-tools를 allowedTools 목록으로 쓰는데, 이는 Qwen Code가 읽는 키와 형태입니다 |
출력 스타일(src/apothem/output-styles/*.md) | name, description. 배포되는 모든 스타일은 Claude Code가 소프트웨어 엔지니어링 지침을 유지하도록 keep-coding-instructions: true도 설정합니다 |
src/apothem/schemas/의 클래스별 스키마는 타입, 형식, enum, 패턴 제한과 길이 제한을 포함한 전체 제약 집합을 담습니다. 스킬 또는 명령의 description은 최대 1,024자이며, 이는 Agent Skills 한도입니다.
3. 검증기
scripts/dev/validate_ecosystem.py는 아티팩트 트리를 순회하며 위의 필수 키 집합을 적용하고, 필수 필드가 누락된 아티팩트마다 [FAIL]을 보고합니다. src/apothem/conformity/frontmatter_grep.py의 쓰기 단위 frontmatter-grep은 PreToolUse Write/Edit 훅 경계에서 같은 형태를 강제합니다.