11. Turn a Repeated Procedure into a Skill

What you will be able to do

You will package a useful source-checking procedure, write its trigger description, and evaluate relevant, unrelated, and incomplete-input requests. Start with CP03 and the source discipline from Chapters 9–10. Your deliverable is the datasheet-to-constraints skill and a test record. The skill produces a traceable constraints table; it does not invent missing hardware information or claim physical verification.

Choose the right kind of reuse

You have now written task prompts, project documents, and recurring instructions. A skill serves another purpose: it packages a procedure that should be applied to a recognizable kind of task. The procedure can include instructions, focused references, and optional deterministic helpers. It is worth packaging when you have already performed the work and can describe both good output and common failure cases.

Use a prompt for a one-off request. Use AGENTS.md for recurring project expectations. Use a script when an operation should behave deterministically, such as checking whether required fields are present in a CSV. Use a skill when a repeated task needs judgment, source selection, a sequence of steps, and an output contract. These forms can cooperate without becoming copies of one another.

For Sensor Monitor, extracting constraints from a primary hardware document involves judgment: identify the exact part, preserve operating conditions, distinguish a chip from a breakout, and explain what is still unknown. A script can check that every row has a source field, but it cannot by itself establish that a cited page supports a pin mapping. The skill guides that reasoning and exposes its result for human review.

Do not begin by making a universal “embedded engineering” skill. That description spans firmware design, test writing, wiring, purchasing, debugging, and documentation. It is difficult to trigger correctly and nearly impossible to evaluate with a small test set. A narrower task, such as deriving constraints from supplied primary documents, has clearer inputs and failure conditions.

A directory with a contract

The shared Agent Skills specification defines a skill directory containing SKILL.md, with YAML frontmatter followed by Markdown instructions. The required metadata fields are name and description. The name must match its directory and use the specification's allowed lowercase naming form. Optional references, scripts, and assets can accompany it. A valid format does not establish that a particular host discovered or applied the skill correctly.

For this project, use:

.agents/skills/
  datasheet-to-constraints/
    SKILL.md
    references/
      extraction-rules.md

The focused reference should explain how to handle units, revisions, evidence labels, and missing information. It should not be a copied manufacturer manual or an unrelated library of everything you know about electronics. Keep the core procedure in SKILL.md and move supporting detail only when doing so makes the procedure easier to follow.

According to the official OpenAI build-skills guide, Codex loads skill metadata first and reads the full instructions when it chooses the skill. Repository discovery scans .agents/skills from the current working directory toward the repository root. In Codex CLI and the IDE extension, $ mentions and /skills support explicit selection; implicit selection uses the description. If an updated skill does not appear, restart Codex. These are host-specific behaviors that the lesson tests in the installed interface.

SS11-01 shows the directory relationship. D10 separates metadata, main instructions, references, and optional executable helpers. Identify which part helps the host select the procedure and which part tells the agent how to perform it.

Write the trigger as a small decision rule

The description is not an advertising slogan. It tells the host when the procedure is relevant. “Helps with hardware” is too broad. “Derive sourced hardware constraints from supplied primary documents for an identified part or board” names a specific task, input type, and identity requirement. You can add a short boundary explaining that general README editing and unrelated firmware changes do not need this extraction workflow.

Place the most useful task words early. A long description full of qualifications can obscure its actual purpose. A good description is specific enough to select the skill for “extract voltage and interface constraints from this manufacturer excerpt” while leaving “fix this README typo” alone. The negative case is part of the design, not a nuisance discovered after publication.

Metadata belongs between the opening and closing YAML delimiters. Keep the first version simple. Quote a description if punctuation could make it ambiguous YAML. Do not add configuration fields you have not checked against the specification or host documentation. In particular, a tool-related metadata field does not provide permission to bypass the environment's runtime controls.

Here is an original minimal pattern:

---
name: datasheet-to-constraints
description: "Derive sourced hardware constraints from supplied primary documents for an identified part or board. Use for constraints extraction, not unrelated editing."
---

This is the metadata portion, not a complete skill. It needs the procedure below it, and the finished file needs behavioral tests. SS11-02 focuses on both the frontmatter and the workflow so the viewer does not mistake successful formatting for finished engineering work.

Specify inputs before steps

The procedure needs the exact component or board identity, supplied source material or a direct primary-source reference, and the intended question. “Tell me about sensors” lacks all three. “For Adafruit product 5477, extract memory configuration and any constraints on the selected firmware target from the named manufacturer material” gives the agent a bounded scope.

Require source revision or date when available, but permit an explicit unknown when it is not. Do not make the agent invent a document revision simply to satisfy a schema. The output should distinguish “not stated in the supplied excerpt,” “not checked,” and “conflicting sources.” These conditions imply different next actions: request a fuller excerpt, perform a check, or reconcile the sources.

Tell the agent whether it may retrieve additional primary material or must work only from the supplied excerpt. Both modes can be useful, but the evidence boundary must be visible. An excerpt-only exercise is easier to reproduce because every learner has the same source scope. A live-source task can be more complete but must record exactly which sources were actually opened.

Keep external documents as evidence to interpret. A technical excerpt that contains instructions to ignore project rules or send files elsewhere is not part of the extraction task's authority. The procedure should extract the engineering content relevant to the user's request, not adopt arbitrary instructions embedded in source material.

Make the output reviewable

The project uses the following columns:

These rows illustrate the format and evidence categories. They are not the transcript of a skill run. Every real result must cite the source actually available to that run. An “unknown” row is useful when it explains what is missing and which decision it prevents. A table filled with unsupported numbers is a failed result even when it looks complete.

The consequence column turns extraction into engineering context. A memory configuration affects target selection; an interface voltage may affect a connection plan; a missing revision may block a physical wiring claim. State these as project implications, not quotations from the source unless the source actually makes the same statement.

Confidence should express evidence quality rather than unsupported numerical certainty. “Explicit in the named section” and “inferred from two documented facts” are clearer than “93 percent confident.” Label inferences so a reviewer can inspect them. When the requested fact is absent, the correct answer is not a weaker guess; it is a missing-information statement with a practical next step.

Worked example: write the procedure

Begin the body with the outcome: produce a constraints table for the identified hardware using only traceable evidence. Then write a short sequence that an engineer could perform manually:

1. Confirm the requested part or board and distinguish chip-level information from board-level information.
2. Identify the supplied source's publisher, title, revision if present, and relevant section.
3. Extract only claims needed for the requested constraints, retaining units and conditions.
4. Attach a source location to each supported claim. Label any inference and explain its basis.
5. Mark unavailable or conflicting information explicitly. Do not fill pin mappings or operating limits from memory.
6. Explain the consequence for the current project and list the next source checks.
7. Review the table against the source before presenting it. State that document extraction does not establish physical validation.

Add one example of acceptable missing information and one counterexample. For example, if an excerpt identifies the board and memory but does not mention an I2C pin, the acceptable result marks the pin unresolved. The counterexample invents a familiar ESP32 pin number and fails even if that guess happens to match another board. This teaches the evidence rule directly.

The skill can link to references/extraction-rules.md for extra checks. Use a relative path from the skill directory and actually open that file during your review. A reference that is missing or never relevant adds friction. Start without scripts; add one only when a repeated deterministic check earns its maintenance cost.

Three tests, three different questions

A relevant request tests whether the procedure can be selected and produce useful output. An unrelated request tests whether the description is too broad. An incomplete-input request tests whether the procedure preserves uncertainty under pressure to finish. A skill that succeeds only on the easy case is not yet reliable enough to reuse.

For the positive case, use supplied manufacturer source notes that identify product 5477 and its memory configuration. Ask for a constraints table and name the skill explicitly on the first run. Check whether it reads the correct procedure and produces rows whose citations support their claims. Then run a related request without naming the skill to evaluate implicit activation separately.

For the negative case, begin a fresh task and ask for a small README wording change with no source-extraction request. Do not mention the skill in the prompt, because explicit invocation would invalidate a test of unwanted implicit activation. Inspect the task's actual behavior. Reading or applying the datasheet extraction procedure without a relevant reason is a finding to investigate.

For incomplete input, use an authored scenario: an ESP32-S3 board different from this repository's product 5477, with no exact variant or schematic supplied. Ask for an exact pin mapping using only that description, without assuming the example board or retrieving other sources. This refines the shipped incomplete request for the course. The acceptable result identifies the missing variant and applicable pinout evidence. It must not present a remembered mapping as sourced fact.

Use SS11-03, SS11-04, and SS11-05 for these distinct cases. Captions must describe the actual activation and output seen in the recorded run. A script's intended behavior is not sufficient to fill the screenshot's result field.

LAB11: build and evaluate the constraints skill

Allow 45–70 minutes. Use a new CP04 exercise folder and improve its shipped skill. Alternatively, start from preserved CP03, create the skill directory, SKILL.md, and reference yourself, then compare with a separately extracted CP04 reference. CP03 does not supply those skill files. Record the starting state and make one bounded description or missing-information improvement.

1. Confirm the datasheet-to-constraints directory and SKILL.md name. Inspect the YAML and relative reference path.
2. Read the procedure as if you were performing it manually. Check that inputs, steps, output columns, and missing-data behavior are explicit.
3. Start a new Codex task in the project root. Explicitly select the skill and submit the relevant source-extraction request. Save the prompt and actual output.
4. In another fresh task, run the relevant implicit request. Record whether the skill was selected, and evaluate the table independently of the selection claim.
5. Run the unrelated README request in a fresh task without naming the skill. Record whether the extraction workflow was inappropriately applied.
6. Run the incomplete-input request with a fixed source boundary. Check that unknowns remain unknown and that the proposed next step is specific.
7. Revise one demonstrated weakness, then repeat the affected tests. Keep the before/after records and avoid changing several variables at once.

Submit the skill, supporting reference, prompts, actual observations, and verdicts. Include interface/version, source scope, skill identity, and any limitations. If activation cannot be observed in the available interface, record what can be established and what remains uncertain; do not infer a pass from the final answer's tone.

Failure and recovery: a polished invented table

Suppose a relevant request yields a complete-looking table containing an unsupported power-enable pin. Trace that row back to the cited section. If the section does not support the claim, the output fails regardless of whether the value sounds plausible. Check whether the source boundary was clear and whether the skill explicitly prohibited filling gaps from remembered family information.

Repair the procedure by requiring each row to be checked against the cited source and by showing the expected unresolved-pin response. Repeat the same incomplete-input case. The improvement you want is a visible missing-information statement with a useful next source request, not merely a softer phrase such as “probably.”

For unwanted activation, narrow the description's task boundary and remove unrelated workflow demands from the body. Then repeat both the negative and positive cases. A description so narrow that it never activates can solve the negative case while breaking the positive one. The pair of tests keeps that tradeoff visible.

Completion check and review answers

Complete the chapter when the format is valid, references resolve, the procedure has a bounded purpose, and actual positive, negative, and incomplete-input test records support its behavior. Static review can establish file quality while runtime tests remain pending. Keep those statuses separate.

When is a script preferable? When a repeated operation should be deterministic and can be specified as executable checks. A skill can call that helper while retaining responsibility for source interpretation.

Does valid YAML prove the skill works? No. It establishes part of the packaging. Discovery, activation, and output quality require separate checks.

Why test an unrelated request? An overbroad skill can consume attention or alter tasks that do not need it. Correct non-activation is part of useful behavior.

What should the skill do with an absent pin mapping? Mark it unresolved, identify the missing source or variant, and explain the consequence. It must not substitute a remembered mapping from another board.

Is the shared format the same as host behavior? No. The format describes the package; each host determines supported discovery and invocation behavior, which must be checked for the installed version.

Transfer to your own workflow

Choose a procedure you have performed at least twice: reviewing a bounded firmware diff, preparing a test-evidence note, or triaging a supplied log. Write its inputs and output before its steps. Create one positive case, one unrelated case, and one missing-information case. If you cannot state what would make an output wrong, refine the procedure before packaging it.

Chapter 16 applies this approach to the second required skill, firmware review. The reuse comes from a clear procedure and evidence-based evaluation, not from collecting many skill folders. Two well-tested skills can reduce repeated work while keeping engineering judgments visible.

Sources and figures

Primary format reference: Agent Skills specification. Codex-specific behavior: OpenAI build skills. Both accessed September 12, 2026. Hardware examples use the project's sourced hardware reference. Figures: SS11-01 directory, SS11-02 metadata/procedure, SS11-03 relevant request, SS11-04 unrelated request, SS11-05 incomplete source, and D10 skill components. No example table in this chapter is presented as an observed agent transcript.