Skills와 SKILL.md

Codex 학습 목차로 돌아가기

이 글에서 완성할 것

Skill은 웹사이트 수정 후 검증처럼 반복하는 절차를 묶습니다. 항상 적용할 프로젝트 조건은 AGENTS.md에 두고 Skill은 특정 작업에 선택합니다. Plugins는 스킬과 서비스 연결을 배포할 수 있습니다.

시작 전 준비

로그인한 Codex CLI 또는 Skills를 지원하는 데스크톱/IDE를 준비합니다. 할 일 자료의 expected를 codex-practice로 복사하고 broken은 별도 후속 실습으로 남깁니다. 두 버전의 파일을 섞지 마세요.

테스트는 Node.js, 미리보기는 Python 3를 사용합니다. 브라우저 도구가 없으면 스킬은 화면 검사를 미실행으로 보고하고 수동 절차를 제공해야 합니다. 지침이 없는 도구를 만들어 주지는 않습니다. 전체 스킬 예제도 내려받을 수 있으며 내용을 읽은 뒤 배치합니다.

이름, 설명, 본문

스킬은 SKILL.md가 들어 있는 폴더가 필요합니다. 맨 위 YAML frontmatter에는 name과 description, 본문에는 절차를 씁니다. Codex는 먼저 이름과 설명을 보고 사용할 때 전체 파일을 읽습니다. 무엇이든 돕는다는 설명은 관련 없는 작업에도 선택되기 쉽습니다.

예제 이름은 todo-acceptance이며 일반 웹 개발이 아닌 Small Steps 검증에 한정합니다. 먼저 스크립트, 외부 서비스, 전역 설치 없이 지침만 사용합니다. 동일한 입력에 동일한 결과를 내는 반복 처리가 필요할 때 scripts를 추가하고 많은 참고 자료는 references에 두어 읽을 조건을 밝힙니다.

1단계: 프로젝트 안에 스킬 만들기

codex-practice 루트에 .agents/skills/todo-acceptance를 만듭니다. 앞의 점도 이름이며 .codex나 점 없는 agents가 아닙니다. Windows는 아래 PowerShell 명령을 사용합니다. 이미 있다면 다른 스킬을 덮기 전에 내용을 확인합니다.

New-Item -ItemType Directory -Force .agents/skills/todo-acceptance

mkdir -p .agents/skills/todo-acceptance

일반 텍스트 편집기로 SKILL.md를 만듭니다. Windows는 .txt가 붙지 않았는지, Linux는 대문자인지 확인합니다. 필요한 전체 구조는 아래와 같습니다. 실습과 함께 관리하며 모든 프로젝트의 개인 스킬로 만들지 않습니다.

codex-practice/
  index.html
  style.css
  app.js
  core.mjs
  core.test.mjs
  .agents/
    skills/
      todo-acceptance/
        SKILL.md

2단계: 전체 스킬 작성

아래는 다운로드와 같습니다. 기존 코드와 테스트를 읽고 실행하며 가능하면 브라우저를 확인해 PASS, FAIL, NOT RUN을 보고합니다. 검사를 통과시키려고 몰래 코드를 고치지 않으므로 문제를 이해한 뒤 수정 여부를 결정할 수 있습니다.

---
name: todo-acceptance
description: Verify the Small Steps todo practice website after a change, using its existing tests and browser checks. Use for acceptance checks of this exercise, not unrelated websites or feature implementation.
---

# Small Steps acceptance

Confirm the requested practice folder contains index.html, style.css, app.js,
core.mjs and core.test.mjs. If these are missing, stop and report the path checked.

Read the existing code, then run `node --test core.test.mjs` from that folder.
Do not rewrite tests or implementation to make an acceptance run pass.

If a browser is available, preview the site on a loopback address with a fresh
browser context. Add Read and Build, complete Read, check Active and Completed
filters, reload, and delete Read. Reject whitespace-only input. Check 390px and
1280px widths and visible Tab focus. Keep existing user browser data unchanged.

Report PASS, FAIL or NOT RUN for each check, with the command, observation or
limitation. Include the working folder and remaining issues. Do not claim that
tests, screenshots, deployment or publication happened without evidence.

If a check fails, report the reproduction and relevant file. If a required tool
is unavailable, report NOT RUN and the manual steps. Finish with results only;
implement fixes only when the user requests them.

이름은 소문자, 숫자, 하이픈을 쓰고 폴더 이름과 맞춥니다. description 앞부분에 대상 범위를 쓰고 본문에는 실제 판단에 영향을 주는 조건을 남깁니다. 이 예제는 추가 패키지나 설정 파일이 필요 없으며 빈 폴더를 늘린다고 더 완성되는 것은 아닙니다.

3단계: 찾고 명시적으로 사용

Codex는 스킬 변경을 감지합니다. 보이지 않으면 세션을 다시 시작하고 작업 폴더를 확인합니다. CLI/IDE는 /skills 또는 $로 찾고 데스크톱은 사이드바 Skills와 현재 선택 UI를 사용합니다. 이름이 보이면 발견 증거일 뿐 실행 증거는 아닙니다.

$todo-acceptance Check this Small Steps practice folder. Report the results without editing files.

데스크톱 선택기가 있다면 todo-acceptance를 고르고 같은 검증 요청을 보냅니다. 다른 동명 스킬이 아닌 프로젝트의 SKILL.md를 읽는지 확인합니다. 같은 이름은 자동 병합되지 않으므로 전역이나 다른 폴더에도 있다면 경로가 중요합니다.

4단계: 정상과 의도된 실패 비교

expected 복사본에서 node --test core.test.mjs는 테스트 세 개가 통과해야 합니다. 보고에 실제 명령과 결과가 있어야 하며 브라우저를 실행했다면 Read, Build, 필터, 새로 고침, 공백 입력의 관찰을 기대합니다. 브라우저가 없으면 NOT RUN이며 통과도 스킬 전체의 실패도 아닙니다.

독립된 broken 복사본을 만들고 그 .agents/skills에 같은 스킬을 넣어 새 작업을 시작합니다. 이 버전은 Completed가 반대로 되어 Read가 완료, Build가 미완료일 때 Build를 잘못 표시합니다. 테스트는 두 개 통과, 한 개 실패해야 합니다. 스킬은 FAIL과 재현 절차를 보고하고 소스를 바꾸지 않아야 합니다.

이 비교로 실패를 정확히 보고하는 절차인지 확인합니다. 형식 검증은 메타데이터와 구조가 해석된다는 뜻이며 에이전트가 절차를 따랐다는 증거는 아닙니다. 반대로 테스트 실패는 스킬이 버그를 찾은 성공일 수 있습니다. 모호한 성공 표시 하나 대신 증거를 나눠 보존합니다.

자료가 부족하면 멈추는지도 확인

expected에서 독립적인 incomplete 사본을 만들고 같은 스킬을 넣습니다. 이 사본의 core.test.mjs만 폴더 밖의 백업 위치로 옮기고 원본 expected와 broken은 유지합니다. incomplete에서 새 작업을 시작해 스킬을 선택하세요. 누락된 파일과 확인한 경로를 알리고 검수를 멈춰야 합니다. 테스트를 새로 지어내거나 다른 사본에서 실행하거나 이전 통과 결과를 재사용하면 안 됩니다. 백업 파일을 원래 위치로 돌려놓은 뒤 다시 검수합니다.

broken은 자료가 갖춰져 있고 실제로 실행한 테스트가 실패합니다. incomplete는 시작 조건을 충족하지 못합니다. 브라우저가 없을 때는 화면 확인만 NOT RUN입니다. 세 상황을 모두 같은 FAIL로 기록하지 마세요. 입력과 선택 조건은 스킬 테스트, 스크립트와 참고 자료 추가는 스킬 리소스에서 이어서 배울 수 있습니다.

문제 해결, 비활성화, 복원

스킬이 없으면 .agents/skills 위치, 실제 확장명, frontmatter의 두 --- 구분자, name과 description을 확인합니다. ZIP을 폴더에 넣기만 한 것은 설치가 아닙니다. 수정 후 Codex를 다시 시작하고 선택기를 확인합니다.

보이지만 쓰지 않으면 명시적으로 선택하거나 $todo-acceptance로 지정하고 이름과 경로를 확인합니다. 자동 선택은 설명과 요청 해석에 따르므로 비슷한 문장이 반드시 실행을 유발하지는 않습니다. 인사에도 검증을 시작한다면 설명을 이 실습 검증으로 좁힙니다.

선택됐지만 테스트를 못 하면 실제 호스트의 Node.js와 작업 폴더의 core.test.mjs를 확인합니다. 모바일 Remote에서도 스킬과 도구는 호스트에 있습니다. 컴퓨터 A에 있다고 B에도 있는 것은 아닙니다. 전제 조건을 숨기려고 모든 부족한 도구를 설치하게 하지 마세요.

진행 중 검증은 작업 안에서 중지합니다. 비활성화하려면 스킬을 프로젝트 검색 위치 밖으로 옮겨 보관하고 재시작해 확인합니다. 설정으로 끄려면 공식 [[skills.config]] 안내를 참고하되 기존 config.toml을 보존합니다. 비활성화해도 이전 보고와 과거 파일 변경은 사라지지 않습니다.

추가 실습과 검증 기록

Small Steps의 필터와 저장을 검증하라는 요청과 오늘의 실습 목표를 설명하라는 요청을 비교합니다. 전자는 적합하고 후자는 전체 검증이 필요 없습니다. 선택 여부, 경로, 결과를 기록해 설명을 조정합니다. 한 번 맞게 선택됐다고 모든 상황을 검증한 것은 아닙니다.

작동 방식은 2026-09-14에 Build skills 공식 문서로 확인했습니다. 예제는 형식 검증을 하며 사이트 핵심과 고장 결과에는 실제 테스트 증거가 있습니다. 자동 선택과 각 Codex UI는 별도 실측이 필요합니다. 다음은 Plugins, MCP, 테스트와 리뷰를 참고하세요.

Codex 학습 목차로 돌아가기

자세한 설명 보기

SKILL.md to Invoke to Output

• AI 도구
• 튜토리얼
• Codex