Skill 스크립트, 참조, 자료

Codex 학습 목차로 돌아가기

목표와 준비

이 단락의 학습 자료: Skills 기초

전체 실습 파일을 다운로드해 codex-skill-lab을 풀고 파일별 설명을 읽으세요. 다음 글의 skill.test.mjs도 포함하지만 전역 스킬을 설치하지 않습니다.

폴더 안의 모든 파일이 자동 실행되지는 않습니다. SKILL.md는 사용 범위와 순서, references는 필요할 때 읽는 규격, assets는 출력 양식, scripts는 실행 코드를 담습니다. 이번에는 JSON 읽기와 집계만 하며 사이트 수정, 네트워크 호출, 게시를 포함하지 않아 각 자원의 역할을 확인할 수 있습니다.

1단계: 스킬과 입력 만들기

Windows, macOS, Linux 모두 파일 관리자나 편집기에서 같은 이름의 구조를 만드세요. data는 스킬 밖 실습 루트에 두어 재사용할 절차와 작업마다 달라지는 입력을 분리합니다. SKILL.md.txt로 저장하거나 같은 이름의 폴더를 한 겹 더 만들지 않았는지 확인하고 사용자 전역 .agents로 복사하지 마세요.

codex-skill-lab/
  data/tasks.json
  .agents/skills/todo-summary/
    SKILL.md
    references/input-format.md
    assets/report.md
    scripts/count-tasks.mjs

data/tasks.json에 전체 입력을 붙이세요. a와 c는 제목이 Read로 같아도 서로 다른 작업이므로 제목을 중복 제거하지 않고 ID로 구분합니다. 잘못 합치는 동작을 드러내기 위한 사례입니다. completed는 따옴표 없는 JSON 불리언이며 마지막 레코드 뒤에 쉼표를 추가하지 마세요.

[
  {"id":"a","title":"Read","completed":true},
  {"id":"b","title":"Build","completed":false},
  {"id":"c","title":"Read","completed":true}
]

2단계: 규격과 보고서 템플릿

references/input-format.md에 다음 규격을 씁니다. 이 실습의 데이터 계약이며 Codex가 모든 JSON에 요구하는 형식은 아닙니다. 필수 필드, 잘못된 입력 처리, 원본 보존 범위를 정의합니다. 우선순위를 추가할 때는 규격, 검사기, 테스트를 함께 수정해 동작이 일치하도록 하세요.

# Task input contract

- Input is a JSON array. An empty array is valid.
- Each record has a nonempty string id, a nonempty string title,
  and a boolean completed value.
- IDs are unique. Repeated titles are allowed and remain separate.
- Extra fields may be present; the summary ignores them.
- Invalid input must fail; do not silently drop or repair records.
- Read input only. Do not change, sort or overwrite the source file.
- Report total, active and completed. total = active + completed.

다음으로 assets/report.md를 만듭니다. 고정 필드로 실행을 비교하며 꺾쇠괄호는 측정값이 아닌 입력할 자리입니다. 실행 전 종료 코드와 개수는 미확정 상태로 두세요. 양식이 완성되어 보여도 실행 보고서는 아닙니다. 이전 수치를 새 작업에 가져오지 않도록 완성 보고서와 템플릿을 분리하세요.

# Task summary

Input: <relative input path>
Command: <exact command>
Exit code: <observed exit code>
Total: <observed total>
Active: <observed active>
Completed: <observed completed>
Input preserved: <verification and result>
Not checked: <remaining checks>

3단계: 독립적으로 검증할 검사기

전체 코드를 scripts/count-tasks.mjs에 저장합니다. 인수로 받은 파일만 읽고 전체 입력을 검증한 뒤 집계합니다. JSON 오류, 중복 ID, 필드 타입 오류는 stderr에 이유를 출력하고 종료 코드 1, 성공은 stdout에 JSON만 출력하고 종료 코드 0입니다. scripts 폴더에 있다는 이유로 신뢰하지 말고 먼저 읽으세요.

import { readFileSync } from 'node:fs';

try {
  if (process.argv.length !== 3) {
    throw new Error('Usage: node count-tasks.mjs <input.json>');
  }
  const tasks = JSON.parse(readFileSync(process.argv[2], 'utf8'));
  if (!Array.isArray(tasks)) throw new Error('Input must be an array');
  const ids = new Set();
  for (const [index, task] of tasks.entries()) {
    if (!task || typeof task !== 'object'
      || typeof task.id !== 'string' || !task.id.trim()
      || typeof task.title !== 'string' || !task.title.trim()
      || typeof task.completed !== 'boolean') {
      throw new Error(`Invalid task at index ${index}`);
    }
    if (ids.has(task.id)) throw new Error(`Duplicate id: ${task.id}`);
    ids.add(task.id);
  }
  const completed = tasks.filter(task => task.completed).length;
  const result = { total: tasks.length, active: tasks.length - completed, completed };
  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
} catch (error) {
  process.stderr.write((error instanceof Error ? error.message : String(error)) + '\n');
  process.exitCode = 1;
}

Windows PowerShell, macOS Terminal, Linux 터미널에서 codex-skill-lab 루트로 이동하고 node --version을 확인한 뒤 같은 명령을 실행하세요. data/tasks.json은 스크립트 위치가 아니라 현재 작업 디렉터리를 기준으로 합니다. scripts 안으로 이동해서 그대로 실행하지 마세요. 스킬에도 이 기준을 명시해야 합니다.

node .agents/skills/todo-summary/scripts/count-tasks.mjs data/tasks.json

{
  "total": 3,
  "active": 1,
  "completed": 2
}

숫자는 고정 입력의 예상값이므로 자신의 터미널 출력을 확인하세요. PowerShell은 $LASTEXITCODE, macOS/Linux는 echo $?를 쓰며 다른 명령이 상태를 바꾸기 전에 읽습니다. data/tasks.json을 다시 열어 세 레코드와 순서, completed 값이 그대로인지 확인하세요.

경로 반례: 스크립트는 있지만 입력 위치가 다름

codex-skill-lab에 있는지, 스킬 폴더 안에 별도 data/tasks.json이 없는지 확인한 뒤 아래 첫 두 줄을 하나씩 실행합니다. 스킬 루트로 이동하면 scripts/count-tasks.mjs는 찾지만 data/tasks.json을 잘못된 위치에서 찾으므로 ENOENT, 종료 1, 성공 JSON 없음이 예상됩니다. 종료 코드를 즉시 읽은 다음 마지막 줄로 연습 루트에 돌아와 앞의 전체 명령을 다시 실행하면 3/1/2로 복구됩니다. SKILL.md 링크와 스크립트 입력 인수는 상대 경로의 기준이 다릅니다.

cd .agents/skills/todo-summary
node scripts/count-tasks.mjs data/tasks.json

cd ../../..

4단계: SKILL.md에서 자원 연결

todo-summary/SKILL.md에 전체 내용을 씁니다. 자원 링크는 SKILL.md 기준이고 실행 명령은 실습 루트 기준입니다. 두 기준을 구분하세요. 이전 todo-acceptance는 유지하고 새 이름 todo-summary로 선택한 절차를 구분합니다.

---
name: todo-summary
description: Summarize a local task JSON array with verified counts. Use for task-count reports, not for editing tasks, website styling, or deployment.
---

# Todo summary

1. Confirm the practice root and the exact input path with the user request.
2. Read [the input contract](references/input-format.md).
   If any required resource is missing or unreadable, stop and report it.
3. Read [the checker](scripts/count-tasks.mjs) before running it.
4. From the practice root, run:

   ```sh
   node .agents/skills/todo-summary/scripts/count-tasks.mjs data/tasks.json
   ```

   Replace the input argument only if the request names another input file.
5. If the command fails, report the actual error. Do not guess counts or repair input.
6. If it succeeds, use [the report template](assets/report.md) in the reply.
7. Include the actual command, exit code and input-preservation check.
   Say which checks were not performed. Do not claim browser testing.
8. Do not edit source data, skill resources, or project code, and do not publish.

Codex는 이름과 설명으로 적합성을 판단하고 선택할 때 전체 지침을 읽습니다. 주 파일에는 안정적인 짧은 절차를 두고 긴 규격과 코드는 직접 연결하면 관리하기 쉽습니다. 매번 모든 자원이 필요하면 분리만으로 사용량이 줄어든다는 보장은 없습니다. 링크가 있다는 사실은 실행 증거가 아닙니다.

5단계: 사용과 결과 검증

실습 루트에서 새 작업을 시작하세요. 데스크톱은 Skills 진입점이나 @, CLI/IDE는 /skills 또는 $로 todo-summary를 선택하고 이름과 파일 위치를 확인합니다. 없다면 루트와 확장자를 점검하고 Codex를 재시작합니다. 다음은 에이전트에게 보내는 요청이며 PowerShell 명령이 아닙니다.

Use the selected todo-summary skill for data/tasks.json.
Read the skill and its linked resources. Run the checker from this practice root.
Return the report in your reply only. Do not write a report file or modify any input.
Include actual output, exit code, and what you verified about input preservation.

규격과 스크립트를 읽었는지, 실제 실행 기록이 있는지, 3/1/2인지, 원본 보존 확인 방법을 설명했는지 검사합니다. 스킬을 사용했다는 말만으로는 부족하며 실행 기록이 없으면 미확인으로 기록하세요. 보고서를 파일로 만들 필요 없이 응답과 직접 실행 결과를 비교하면 됩니다.

입력을 바꾸고 이전 숫자를 재사용하는지 확인

tasks.json은 보존하고 아래 내용을 data/tasks-next.json으로 저장합니다. 연습 루트에서 아래 명령을 실행하면 total 2, active 2, completed 0이 예상됩니다. 새 작업에서 앞의 스킬 요청은 입력 경로만 바꾸고 예상 숫자는 알려주지 않습니다. 새 보고서는 새 경로와 도구 출력을 제시해야 하며 3/1/2를 재사용하면 안 됩니다. 이전 경로로 다시 실행해 3/1/2인지 확인하면 두 입력이 덮어써지지 않았는지도 확인할 수 있습니다.

[
  {"id":"next-a","title":"Plan","completed":false},
  {"id":"next-b","title":"Check","completed":false}
]

node .agents/skills/todo-summary/scripts/count-tasks.mjs data/tasks-next.json

실패 사례, 복원과 다음 단계

input-format.md를 잠시 input-format.saved.md로 바꿉니다. 그다음 새 작업을 열고 작업 폴더가 codex-skill-lab인지 확인한 뒤 스킬을 명시적으로 선택하세요. 이전에 읽은 규격이나 보고서를 전달하지 않아야 과거 대화 내용이 누락을 가리지 않는 상태에서 관찰할 수 있습니다. 필요한 규격이 없다고 알리고 검증 완료 보고서 작성을 중단해야 하며 대체 규격을 지어내면 안 됩니다. 이름을 복구한 뒤 또 다른 새 작업에서 재검사하세요. 누락 상태에서도 수치를 출력했다면 미검증 표시를 확인하고 스킬 실패 사례로 기록합니다.

스크립트를 못 찾으면 스킬 루트와 작업 루트를 구분하고, 합계 2이면 같은 제목을 합쳤는지, 문자열 completed가 통과하면 실행한 검사기 버전을 확인하세요. 모든 스킬을 재설치하지 말고 원본을 보존한 채 누락 파일, 잘못된 데이터, 경로 오류를 하나씩 수정해 원인을 구분합니다.

이 글의 자료 검증은 Node.js 검사기의 재현 가능한 입출력입니다. 선택, 자동 활성화, 에이전트 준수는 자신의 환경에서 관찰해야 하며 스크립트 성공으로 대체하지 않습니다. 다음 스킬 검증과 수정은 빈 입력, 중복 ID, 타입 오류, 범위 밖 요청을 추가해 코드 정확성과 올바른 사용을 구분합니다. 그림 1은 입력/계약, 2는 실행, 3은 보고서 확인입니다.

Codex 학습 목차로 돌아가기

자세한 설명 보기

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 도구
• 튜토리얼
• Codex