Skill scripts, references and assets

Back to the Codex learning hub

Goal and preparation

Lessons and resources mentioned here: Skills basics

You can download the complete practice files, extract codex-skill-lab and follow the file-by-file explanations. It also includes the next lesson's skill.test.mjs; it does not install a global skill.

A folder does not execute every file automatically. SKILL.md describes when and how to use the workflow; references holds specifications to read when needed; assets supplies an output template; scripts contains executable code. This exercise only reads and counts JSON tasks, with no website edits, network calls or publication, so each resource has an observable purpose.

Step 1: Create the skill and input

Create this structure in your file manager or editor, using identical filenames on Windows, macOS and Linux. Keep data at the practice root, outside the skill: reusable workflow and per-task input have different lifetimes. Check that SKILL.md was not saved as SKILL.md.txt or nested inside an extra duplicate folder. Do not copy it into your global user .agents directory.

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

Paste the complete input into data/tasks.json. Records a and c share the title Read but represent distinct tasks; identify records by ID rather than deduplicating titles. This makes accidental merging visible. completed uses JSON booleans true/false, without quotation marks, and the final record has no trailing comma.

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

Step 2: Write the specification and report template

Write this specification in references/input-format.md. It is the exercise's data contract, not a universal JSON requirement imposed by Codex. It defines required fields, invalid-input behavior and input preservation. If you later add priorities, update the specification, checker and tests together so they continue describing the same behavior.

# 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.

Create assets/report.md next. Stable fields make runs comparable; angle-bracketed text marks values to fill, not measured results. Leave the exit code and counts unresolved until execution. A complete-looking template is not a completed report. Keep the template separate from finished reports to prevent carrying yesterday's numbers into a new task.

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

Step 3: Build an independently verifiable checker

Save the entire program as scripts/count-tasks.mjs. It reads only the argument file and validates all input before emitting counts. Malformed JSON, duplicate IDs or invalid field types produce an explanation on stderr and exit code 1. Success writes only JSON to stdout and exits 0. Read scripts before running them; placement inside a scripts folder does not establish trust.

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;
}

In Windows PowerShell, macOS Terminal or a Linux terminal, enter the codex-skill-lab root, check node --version, then run this identical command. data/tasks.json resolves from the working directory, not the script's directory. Do not enter scripts and paste the command unchanged. The skill must make that working-directory requirement explicit.

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

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

These are expected values for the fixed fixture; inspect your terminal's actual output. In PowerShell read $LASTEXITCODE; on macOS/Linux use echo $?. Read it before another command changes the last exit status. Reopen data/tasks.json and verify all three records, their order and completed values are unchanged.

Path counterexample: the script exists but the input is elsewhere

Start in codex-skill-lab; confirm no data/tasks.json exists inside the skill folder. Run the first two lines separately: the script is found, but its input path is wrong. Expect ENOENT, exit 1 and no success JSON. Read the exit code immediately; use the final line to return to the practice root, then rerun the earlier full command for 3/1/2. SKILL.md links and input arguments use different path bases.

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

cd ../../..

Step 4: Connect the resources in SKILL.md

Write the complete SKILL.md under todo-summary. Resource links are relative to SKILL.md, while the execution command explicitly starts at the practice root. Distinguish these two bases. Keep the earlier todo-acceptance skill; the new name todo-summary lets you identify the intended workflow in the picker.

---
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 uses the name and description to identify relevant skills, then reads full instructions when selecting one. Keep a stable short workflow in the main file and directly link longer specifications and code. This improves maintainability; splitting files does not guarantee lower usage when a task needs every resource. A linked script is not evidence of execution.

Step 5: Use the skill and verify delivery

Start a new task from the practice root. On desktop select todo-summary through the skills entry or @ picker; in CLI/IDE use /skills or $. Check its name and file location. If absent, check the project root and filename extension, then restart Codex. The following is a natural-language request to the agent, not a PowerShell command.

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.

Verify that it read the contract and script, actually ran the command, obtained 3/1/2 and explained its input-preservation check. Saying it used the skill is insufficient; without execution evidence, mark execution unconfirmed. The report need not become a file: compare the reply directly with your manual terminal result.

Change the input and check for reused counts

Keep tasks.json; save the following as data/tasks-next.json. From the practice root, run the command for expected total 2, active 2, completed 0. In a fresh task, change only the earlier skill request's input path and omit expected counts. Require the new path and tool output. Rerun the old path for 3/1/2 and verify neither input was overwritten.

[
  {"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

Failures, restoration and next steps

Temporarily rename input-format.md to input-format.saved.md, then start a fresh task, verify codex-skill-lab and explicitly select the skill. Do not supply previously read contracts or reports: this case must observe the missing file without cached conversation context. Expect the skill to identify the required contract as missing and stop before producing a verified workflow report, without inventing a replacement. Restore the name and retest in another fresh task. If the missing-file case produces counts anyway, inspect whether they are labeled unverified and record a skill failure.

If the script is missing, distinguish skill root from working root. A total of 2 suggests same-title merging; accepted string completed values suggest a different checker version. Do not reinstall every skill. Preserve the original input and correct missing files, bad data and wrong paths separately so each change has an attributable effect.

This lesson verifies reproducible Node.js checker inputs and outputs. Observe skill selection, implicit activation and agent compliance in your own surface; script success does not establish those. Skill testing and repair adds empty input, duplicate IDs, type errors and out-of-scope requests, separating checker correctness from correct skill use. Diagram 1 is input/contract, 2 execution and 3 report verification.

Back to the Codex learning hub

Read the full description

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

• AI tools
• Tutorials
• Codex