스킬 시스템 파운드리은(는) 무엇을 하나요?
AI 에이전트에 구애받지 않는 스킬 시스템을 구축하기 위한 메타 스킬입니다. 2계층 아키텍처(스킬과 역할), 템플릿, 검증 도구, 그리고 Agent Skills 사양 기반의 교차 플랫폼 작성 가이드를 제공합니다.
프로젝트 컨텍스트
이 저장소는 하나의 스킬(skill-system-foundry/)과 그 테스트 스위트(tests/)를 포함합니다. 이 스킬은 메타 스킬입니다. 즉, 그 도메인은 다른 스킬을 구축하는 것입니다. 애플리케이션이 아닙니다. 서버, 데이터베이스, 프론트엔드가 없습니다.
언어: Python 3.12+ (표준 라이브러리만 사용 — 프로덕션 코드에 타사 임포트 없음).
개발 종속성: coverage (테스트 커버리지 측정 전용, 정확한 버전은 requirements-dev.txt 참조).
저장소 구조:
.
├── AGENTS.md ← 이 파일
├── CLAUDE.md ← AGENTS.md로의 심볼릭 링크
├── CONTRIBUTING.md ← 기여자 가이드라인
├── README.md ← 저장소 개요
├── .coveragerc ← 커버리지 설정 (70% 임계값, 브랜치)
├── .python-version ← Python 버전 (현재 값은 파일 참조)
├── requirements-dev.txt ← coverage만 포함
├── skill-system-foundry/ ← 메타 스킬 자체
│ ├── SKILL.md ← 진입점 (라우터)
│ ├── README.md ← 스킬 문서
│ ├── capabilities/ ← 독립적인 기능 모듈
│ │ ├── skill-design/
│ │ │ └── capability.md ← 스킬, 기능, 역할, 매니페스트 생성
│ │ ├── validation/
│ │ │ └── capability.md ← 스킬 검증, 시스템 감사
│ │ ├── migration/
│ │ │ └── capability.md ← 플랫 스킬을 라우터 패턴으로 마이그레이션
│ │ ├── bundling/
│ │ │ └── capability.md ← 스킬을 zip 번들로 패키징
│ │ └── deployment/
│ │ ├── capability.md ← 도구, 래퍼, 심볼릭 링크에 배포
│ │ └── references/
│ │ └── symlink-setup.md ← 플랫폼별 심볼릭 링크 명령어
│ ├── references/ ← 필요 시 컨텍스트에 로드되는 가이드
│ │ ├── authoring-principles.md ← 교차 플랫폼 스킬 작성 합의
│ │ ├── architecture-patterns.md ← 독립형 vs 라우터 결정
│ │ ├── agentskills-spec.md ← 사양 준수 가이드
│ │ ├── tool-integration.md ← 도구별 경로 및 배포
│ │ ├── directory-structure.md ← 전체 레이아웃 및 규칙
│ │ ├── anti-patterns.md ← 일반적인 실수
│ │ ├── claude-code-extensions.md
│ │ ├── codex-extensions.md
│ │ └── cursor-extensions.md
│ ├── assets/ ← 스캐폴딩용 템플릿
│ │ ├── skill-standalone.md
│ │ ├── skill-router.md
│ │ ├── capability.md
│ │ ├── role.md
│ │ └── manifest.yaml
│ └── scripts/ ← 검증, 스캐폴딩, 번들링 도구
│ ├── lib/ ← 공유 로직 (모듈당 단일 책임)
│ │ ├── configuration.yaml ← 모든 검증 규칙의 단일 진실 공급원
│ │ ├── constants.py ← YAML 로드, Python 상수로 노출
│ │ ├── validation.py ← 공유 이름/필드 검증
│ │ ├── references.py ← 참조 스캔 및 그래프 순회
│ │ ├── bundling.py ← 핵심 번들링 로직
│ │ ├── manifest.py ← 매니페스트 파싱 및 검증
│ │ ├── codex_config.py ← Codex agents/openai.yaml 검증
│ │ ├── yaml_parser.py ← 표준 라이브러리 전용 YAML 서브셋 파서
│ │ ├── frontmatter.py ← YAML 프론트매터 추출
│ │ ├── reporting.py ← 구조화된 출력 포맷팅
│ │ └── discovery.py ← 스킬 디렉토리 발견
│ ├── validate_skill.py ← 단일 스킬 검증
│ ├── audit_skill_system.py ← 전체 스킬 시스템 감사
│ ├── scaffold.py ← 템플릿에서 새 컴포넌트 스캐폴딩
│ └── bundle.py ← 배포용 번들 (zip)
├── tests/ ← 포괄적인 테스트 스위트 (현재 파일은 tests/ 참조)
│ ├── helpers.py ← 공유 테스트 유틸리티
│ └── test_*.py ← 소스 모듈당 하나의 테스트 파일
├── .agents/ ← 내부 개발 스킬 (배포되지 않음)
│ └── skills/
│ ├── commit-conventions/ ← 커밋 메시지 형식 및 규칙
│ ├── critique/ ← 계획 및 솔루션에 대한 건설적인 비판
│ ├── git-release/ ← 릴리스 수명 주기 가이드
│ ├── github-actions/ ← CI/CD 워크플로우 작성 및 검토
│ ├── local-code-review/ ← 로컬 자동 검사 및 diff 분석
│ ├── markdown-docs/ ← 문서 품질 강제
│ ├── python-scripts/ ← Python 코드 품질 규칙
│ ├── review/ ← 인간 PR 리뷰 프로세스 가이드
│ ├── shell-scripts/ ← 셸 스크립트 안전성 및 일관성
│ ├── skill-authoring/ ← 메타 스킬 구조 일관성
│ ├── solution-design/ ← 구현 전 솔루션 계획
│ ├── validate-skill-spec/ ← 스킬 구조 및 사양 준수 검증
│ └── yaml-config/ ← configuration.yaml 거버넌스
├── .claude/ ← Claude Code 설정 및 스킬 심볼릭 링크
│ └── skills/ ← Claude Code용 .agents/skills/로의 심볼릭 링크
├── .claude-plugin/ ← Claude Code 플러그인 마켓플레이스 설정
│ ├── plugin.json
│ └── marketplace.json
└── .github/
├── codex/ ← Codex 리뷰 설정
│ └── review-reference.md ← 저장소별 리뷰 가이드
├── scripts/ ← CI 도우미 스크립트 (bash + Python)
├── workflows/ ← GitHub Actions CI/CD
│ ├── python-tests.yaml ← 테스트 + 커버리지 + 배지 업데이트 (ubuntu + windows)
│ ├── shellcheck.yaml ← .github/scripts/*.sh 린트
│ ├── codex-code-review.yaml ← codex-ai-code-review-action을 통한 Codex PR 리뷰
│ └── release.yml ← zip 번들 + 릴리스 자산 업로드
├── instructions/ ← Copilot/Codex용 리뷰 규칙
│ ├── markdown.instructions.md ← **/*.md에 적용
│ └── scripts.instructions.md ← scripts/**/*.py에 적용
├── copilot-instructions.md ← 최상위 리뷰 가이드
└── CODEOWNERS ← .github/에 대한 코드 소유자 승인 필요
제약 사항
다음 제약 사항은 전체 코드베이스에서 변경 불가능합니다.
- 표준 라이브러리만 — 프로덕션 코드에
pip install종속성 없음. 스크립트는 Python 3.12+가 설치된 모든 곳에서 실행되어야 합니다. - Python 3.12 호환성 — 3.13+의 기능을 사용하지 마십시오.
- YAML의 검증 규칙 — 제한, 패턴, 예약어는
scripts/lib/configuration.yaml에 있습니다. 검증 규칙을 Python에 하드코딩하지 마십시오. os.path만 —pathlib를 사용하지 마십시오. 둘을 혼용하지 마십시오.- 모든 함수 시그니처에 타입 힌트 — 내장 제네릭(
list,dict,tuple) 및X | None을 사용하십시오. - 모든
open()호출에encoding="utf-8". - 상수의 오류 수준 —
lib/constants.py의LEVEL_FAIL,LEVEL_WARN,LEVEL_INFO를 사용하고, 문자열을 하드코딩하지 마십시오. - 검증 함수는
(errors, passes)튜플을 반환 — 검증 실패에 대해 예외를 발생시키지 마십시오. - 셸 스크립트는
set -euo pipefail을 사용하고 상단에서${VAR:?}로 환경 변수를 검증합니다. - Actions는 태그가 아닌 커밋 SHA에 고정.
- 모든 스크립트 진입점은
--json을 지원 —lib/reporting.py의to_json_output()을 통해 기계 판독 가능한 출력.
개발 워크플로우
테스트 실행
python -m coverage run -m unittest discover -s tests -p "test_*.py" -v
python -m coverage report
커버리지 임계값: 70% 브랜치 커버리지 (.coveragerc에 설정됨). CI는 ubuntu-latest 및 windows-latest에서 Python 3.12로 테스트를 실행합니다.
메타 스킬 검증
cd skill-system-foundry
python scripts/validate_skill.py . --allow-nested-references --verbose
python scripts/audit_skill_system.py .
--allow-nested-references 플래그는 이 메타 스킬이 의도적으로 중첩 참조를 사용하기 때문에 필요합니다. 이 배포 저장소에서는 감사에서 skills/ 디렉토리가 누락되었다는 경고가 하나 예상됩니다.
셸 스크립트 린트
shellcheck .github/scripts/*.sh
커밋 메시지 형식
Update <component> and <component>
Add <new-thing> to <location>
Fix <issue> in <component>
아키텍처 규칙
스킬 시스템은 정확히 두 개의 계층으로 구성됩니다.
- 스킬 — 표준적이고 AI에 구애받지 않는 지식. 집중된 작업을 위한 독립형, 복잡한 도메인을 위한 라우터.
- 역할 — 책임, 권한, 제약 조건 및 핸드오프 규칙을 사용하여 2개 이상의 스킬을 구성하는 오케스트레이션 계약.
종속성은 엄격하게 아래 방향으로 흐릅니다: 역할 → 스킬 → 기능. 역방향은 절대 안 됩니다. 기능은 선택 사항이며, 3개 이상의 고유한 작업이 상호 배타적인 트리거를 가질 때만 필요합니다.
코드 구성
- 진입점 (
scripts/*.py) — 얇은 래퍼: 인수 파싱, 출력 포맷팅,sys.exit(). 모든 것은scripts/lib/에 위임합니다. - 라이브러리 모듈 (
scripts/lib/*.py) — 도메인 로직. 전용 출력 헬퍼(reporting.py)를 제외하고print()또는sys.exit()를 사용하지 않습니다. - 상수 (
scripts/lib/constants.py) — Python의 구조적 상수,configuration.yaml에서 로드된 검증 규칙. 모든 YAML 값은 사용자 정의 파서에 의해 문자열로 반환됩니다 —constants.py에서int()로 변환하십시오. - 테스트 (
tests/) — 소스 모듈당 하나의 테스트 파일. 기능별로 그룹화된 설명적인 클래스 이름을 가진unittest.TestCase. 시각적 명확성을 위한 섹션 구분자 (# ===...).
문서 표준
- 간결성 우선 — 모델이 이미 가지고 있지 않은 컨텍스트만 추가합니다.
- 스킬 설명에서 3인칭 — "I validate skills"가 아닌 "Validates skills".
- 개념당 하나의 용어 — 파일 내부 또는 파일 간에 동의어를 혼용하지 않습니다.
- 점진적 공개 —
SKILL.md는 500줄 미만,references/에 세부 사항, 한 수준 깊이의 상호 참조. - 프론트매터 — 여러 줄 설명에는 접힌 블록 스칼라(
>), 특수 문자는 따옴표 처리. - 오류 수준 태깅 — 사양 규칙에는
[spec], 플랫폼 제한에는[platform: X], 규칙에는[foundry].
리뷰 가이드
자세한 리뷰 규칙은 .github/instructions/에 있습니다.
| 파일 | 적용 대상 | 초점 |
|---|---|---|
.github/copilot-instructions.md | 모든 파일 | Agent Skills 사양 준수, 아키텍처 |
.github/instructions/markdown.instructions.md | **/*.md | 문서 품질, 설명 트리거 |
.github/instructions/scripts.instructions.md | scripts/**/*.py | 코드 품질, stdlib 전용, 타입 힌트 |
자동화된 검증(validate_skill.py, audit_skill_system.py)은 많은 프론트매터, 명명, 줄 수 및 구조적 검사를 처리합니다. 수동 리뷰는 여전히 마크다운 파일 참조 규칙(스킬 루트 상대 경로 포함), 경로 유효성, 점진적 공개, 설명 품질, 아키텍처 정당성 및 의미적 일관성을 확인합니다.
릴리스 프로세스
버전은 skill-system-foundry/SKILL.md 프론트매터(metadata.version)에 있습니다. 태그는 vX.Y.Z를 미러링합니다. release.yml 워크플로우는 zip을 자동으로 번들링하고 릴리스 자산으로 업로드합니다. 태깅하기 전에 전체 검증 및 테스트를 실행하십시오.