Choose the right job for a skill

Understand the approach

A skill packages a repeatable way to handle a recognizable task. Its value comes from making a good process available when needed, rather than repeatedly pasting the same instructions into every conversation. Start with the job you want done: review a README for missing setup information, turn release notes into a user announcement, or reconcile a small data export. A skill does not supply missing credentials, create a service integration, or establish that the process itself is sound.

Separate three responsibilities before authoring. The task prompt identifies today's input and result. AGENTS.md describes stable working agreements for a project. A skill describes a reusable procedure with its own trigger, required inputs and output. A rule such as preserve existing changes usually belongs in project instructions; a procedure for comparing a README against the repository's actual run commands is a plausible skill. Keep facts that change, such as the latest command names, in their canonical project files and instruct the skill to read them.

The practice workflow is readme-evidence-review. It should examine a specified README and produce a table of missing information with evidence and suggested additions. It must distinguish an absent instruction from an instruction that exists but has not been tested. That difference matters: a confident guide can still contain a broken command. Start with instruction-only behavior. The complete practice package then adds a limited deterministic script because comparing declared command names benefits from exact repeatable checks. It still does not execute the application, install anything, or prove host invocation.

Start with an observable before/after rather than another proposed prompt. The supplied preparer builds a new scratch project containing the complete skill plus a broken README and package.json. Running its helper produces UNKNOWN_SCRIPT at line 4 and missing verification guidance. Correct the copied README to document the real dev/test scripts, then the same helper should return no findings. This gives you a reusable evidence contract and a contrasting negative input before investigating actual Codex selection. The preparer refuses existing destinations and writes no personal settings.

Practice and acceptance

A reusable procedure earns its place by producing the same evidence contract across contrasting inputs.

Try it step by step

1. Read native-client.md, cases.json and the rubric; predict which findings the supplied broken and complete inputs should produce.
2. Choose a task you have performed repeatedly. Write its inputs, intended reader and one concrete output; exclude adjacent work such as publishing the result.
3. Create a small practice README with a project purpose and run instructions but no verification instructions. Keep a second version with all three sections.
4. Write two requests that should use readme-evidence-review and two unrelated requests that should not. This defines a useful activation boundary before implementation.
5. Ask Codex to evaluate your proposed skill using the example. Compare its recommendation with the actual repeated task, then record the agreed scope in a scratch note.

A useful starting example

Illustration · adapt before use.

node labs/skill-workflow/prepare-scratch.cjs ../readme-skill-practice
# The receipt supplies the real new project path. In that folder:
node .agents/skills/readme-evidence-review/scripts/review.cjs .

Check your result

• The proposed skill has one recognizable user goal and a reviewable output.
• You can give a relevant request and an unrelated request without an ambiguous overlap.
• The workflow names the evidence it needs and does not imply access to tools that are unavailable.
• Helper results, actual host activation and unexecuted application commands remain distinguishable.

Common mistakes

• Turning every personal preference into a skill with a broad, overlapping description.
• Treating an installed skill as proof that a workflow is accurate, authorized or connected to live data.