oozoofrog/codex-skill-audit

Codex Skill Audit

Codex 스킬 저장소를 공식 구조와 운영 관점에서 감사하고 개선점을 제안합니다.

When to use

다음 요청에 적합합니다.

• .agents/skills 구조 점검
• Codex 스킬 저장소 품질 감사
• discovery 문제 진단
• 스킬 이름 중복/설명 부정확/본문 비대화 점검
• agents/openai.yaml와 SKILL.md 정합성 확인

Do not use when

• 새 스킬을 만들거나 구조를 재작성해야 하는 작업 → codex-skill-bootstrap
• plugin packaging, marketplace, legacy residue 감사가 주목적인 작업 → plugin-doctor
• 저장소 전체가 아니라 instruction 계층 자체를 다루는 작업 → agent-context-*

Quick start

1. audit_codex_skill_repo.py [target]로 결정적 감사를 먼저 수행한다.
2. trigger boundary, references 분리, review harness, metadata를 수동 점검한다.
3. critical / warning / info / strength로 정리하고 바로 고칠 파일부터 제안한다.

Use these resources

• references/audit-checklist.md — 사람이 직접 볼 감사 기준
• scripts/audit_codex_skill_repo.py — 반복 가능한 구조 점검 스크립트
• schemas/report.schema.json — machine summary JSON shape
• ../../../docs/evaluator-output-contract.md — evaluator 출력 공통 계약
• ../../../docs/review-harness.md — repo-wide review harness 기준

Audit workflow

1. Find the target root

명시 경로가 없으면 현재 repo를 기준으로 감사합니다.

2. Run the deterministic audit

가능하면 먼저 아래 스크립트를 실행합니다.

python3 .agents/skills/codex-skill-audit/scripts/audit_codex_skill_repo.py [target]

이 스크립트는 최소 다음을 확인합니다.

• repo root에 AGENTS.md 존재 여부
• .agents/skills/**/SKILL.md 탐색
• frontmatter의 name, description
• kebab-case 이름 규칙
• 중복 스킬 이름
• 과도하게 긴 SKILL.md
• skill dir 안의 불필요한 README.md
• agents/openai.yaml 존재 여부와 기본 정합성

3. Inspect qualitative issues

스크립트 결과 이후 수동으로 아래를 점검합니다.

• description이 너무 넓거나 너무 좁지 않은가
• When to use, Do not use when, Quick start, Output expectation이 operator 관점에서 충분히 명확한가
• SKILL.md 본문이 핵심 절차 중심인가
• 상세 설명이 references/로 충분히 분리되었는가
• script가 꼭 필요한 곳에만 들어가 있는가
• repo-level AGENTS.md 규칙과 충돌하지 않는가
• 필요한 스킬에 Review Harness 선언이 있고, mode가 실제 위험도와 맞는가

4. Report by severity

결과는 다음 4단계로 정리합니다.

• critical — 발견/실행 자체가 깨짐
• warning — 구조는 되지만 품질 저하 위험
• info — 선택적 개선
• strength — 잘한 점

5. End with concrete fixes

항상 아래 형태로 마무리합니다.

1. 바로 고쳐야 할 파일
2. 권장 수정안
3. 필요하면 신규 파일 제안
4. plugin packaging 전환 전 준비사항

Review Harness

• mode: none
• 공통 기준: ../../../docs/review-harness.md
• generator: 상위 스킬이 만든 skill 구조/metadata 변경
• evaluator: 이 스킬 자체와 audit_codex_skill_repo.py가 evaluator-native 감사 역할을 수행한다
• 평가축: 구조 적합성, discovery readiness, frontmatter 품질, openai.yaml 정합성, review harness 선언 적절성
• artifacts/evidence: deterministic audit report, frontmatter, 경로 구조, metadata consistency
• pass condition: critical 구조 문제 없이 discovery 가능한 상태여야 한다
• 자동 다음 행동: pass면 종료, warning이면 문서/메타데이터 정리, critical이면 codex-skill-bootstrap 기준으로 구조를 재정비한 뒤 재감사한다

Output expectation

최종 결과는 다음 형식을 권장합니다.

# Codex Skill Audit Report

## Summary
...

## Findings
- [critical] ...
- [warning] ...
- [info] ...

## Recommended fixes
1. ...
2. ...

deterministic audit script는 아래 artifact를 함께 지원하는 편을 권장합니다.

• stdout: 사람이 읽는 Markdown 보고서
• --json-out <path>: schemas/report.schema.json에 맞는 machine summary JSON