# Codex Skill Audit

> Use this skill when the user wants to audit a Codex skill or skill repository for official structure compliance, discovery readiness, frontmatter quality, oversized SKILL bodies, stale `agents/openai.yaml`, duplicate skill names, or missing repo-level AGENTS guidance.

- Skill: `oozoofrog/codex-skill-audit` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add oozoofrog/codex-skill-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oozoofrog/codex-skill-audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: oozoofrog (https://skillmd.com/u/oozoofrog)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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

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

```bash
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

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

```markdown
# 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