Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Build an agent skill as a small, reusable directory: write its purpose and workflow in SKILL.md, add Python and other supporting files only when they help complete the task, then evaluate whether the skill is selected for the right requests and produces the expected result. Setup differs between local and hosted/API environments, so choose the target environment before packaging the skill.
What an AI agent skill contains
A skill is a directory of reusable instructions and supporting files, not just a prompt. Its required core is SKILL.md, which provides the skill’s identity and tells the agent how to carry out the workflow. References, templates, assets, test fixtures, and scripts are optional additions when the task needs them. OpenAI’s Skills documentation describes the directory structure and distinguishes local execution from hosted, container-based use.
A minimal project might look like this:
my-skill/
├── SKILL.md
├── scripts/
│ └── transform.py
├── references/
│ └── format-guide.md
└── assets/
└── example.csvThis is a possible layout, not a requirement to create every folder. For a short instruction-only workflow, a directory containing just SKILL.md may be enough.
Write the skill’s name and description first
Start the file with front matter that identifies the skill. Give it a concise, distinctive name and describe both the task it handles and the kinds of requests that should activate it. The description matters because it helps the agent decide whether to use the skill; a broad or vague description can make routing less reliable. OpenAI’s article on systematically testing agent skills discusses the role of skill descriptions and evaluation.
#1 Best Overall
---
name: csv-cleanup
description: Clean and validate CSV files when a user asks to normalize columns, remove malformed rows, or prepare a CSV for import.
---Choose a name that makes the skill easy to distinguish from other available skills. In the description, be specific enough to signal intended requests without claiming unrelated work.
Make the workflow explicit in SKILL.md
After the front matter, write instructions that an agent can follow and that a person can check. State what input the workflow expects, what steps to perform, what output to produce, and how to tell when the task is complete. Keep the main procedure in SKILL.md; add a reference file or template when it would otherwise make the instructions unwieldy or when the material is useful separately.
- Define the input. Specify the expected files, data, or user-provided details, along with how to handle missing or ambiguous input.
- Describe the procedure. Put steps in execution order. Distinguish required actions from optional ones, and identify any decisions the agent must make.
- Specify the output. Name the format, destination, and essential contents. Avoid relying on words such as “good” or “clean” without explaining what they mean.
- Add completion checks. Describe observable conditions for success, such as a required output file existing or a validation step passing.
For example, a CSV-cleanup skill could require the agent to preserve the source file, normalize column names according to a stated rule, and report rows it could not parse. Those rules are illustrative; define them to suit the actual task rather than assuming one CSV policy fits every project.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDecide whether Python belongs in the skill
Python is optional. Add a script when a deterministic transformation, repeatable computation, or other executable step materially benefits from code. For a workflow that is primarily guidance or judgment, instructions alone may be clearer and easier to maintain.
| Approach | Use it when | What to include |
|---|---|---|
| Instruction-only | The task is adequately handled through clear instructions and does not need a repeatable computation. | SKILL.md; references or templates only if useful. |
| Script-backed | A step benefits from deterministic processing, repeatable calculations, or a helper program. | SKILL.md, the script, and any task-specific dependencies, fixtures, or assets. |
Keep scripts and their supporting files inside the skill bundle where practical. In the instructions, state the expected working directory, how to invoke the script, what inputs it accepts, and what output or errors to expect. A script that assumes an unstated current directory or environment can fail even when its logic is sound.
The OpenAI cookbook example demonstrates a bundle with SKILL.md, run.py, requirements.txt, and a sample CSV. Its packages and commands support that particular CSV workflow; they are not general requirements for every skill.
Test invocation and results, not just file structure
A directory can be formatted correctly and still be unclear, selected for the wrong requests, or fail to produce the needed output. Before testing, write down the expected behavior. Use positive cases that should invoke the skill, negative cases that should not, and output checks tied directly to its instructions.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Case | Example request | What to check |
|---|---|---|
| Intended trigger | “Normalize these CSV column names and flag malformed rows.” | The skill is selected and the result follows its stated input, processing, and reporting rules. |
| Boundary or ambiguous request | “Can you explain what this CSV contains?” | The skill is selected only if its description and instructions cover this task; otherwise, it should not be forced into the workflow. |
| Unrelated request | “Write a short note thanking my neighbor.” | The skill is not selected. |
For each run, record the request, whether the skill was invoked, and whether the output met the checks. If an intended request misses the skill, tighten its description or clarify its scope. If an unrelated request triggers it, narrow the description. If invocation is correct but the result is wrong, improve the workflow instructions or script and rerun the affected cases. OpenAI’s evaluation guidance describes assessing skills systematically against tasks; successful results on a small set do not guarantee the same behavior across every model or environment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose the setup for the environment you will use
Decide where the skill must be discovered before following setup steps. OpenAI’s API guide describes local execution and hosted, container-based use as distinct approaches; for Agents API use, skill directories are discovered through configured capability directories. The cookbook’s API example is a separate script-backed example. Do not combine paths or setup assumptions from different surfaces without checking that they apply to the environment you are targeting.
- Local use: Put the skill where the relevant local environment discovers skills, following that environment’s documentation.
- Hosted or API use: Follow the configuration and packaging steps for the specific API or hosted surface, including how its capability directories or files are supplied.
Before any API run that may incur usage, do local checks first where the example or environment supports them. The cookbook explicitly recommends local checks before opting into API requests in its example. Neither a successful file check nor an example from official documentation establishes that a particular skill works in your own setup: run your evaluation cases in the target environment and report only the results you observe.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →
