Instructions are different from tools
A skill describes how to carry out a task. A tool supplies an executable capability. Skills can point to scripts, reference documents, and templates, but they do not independently grant network access or authorization.
Organize a skill directory
Put the name, description, and instructions in SKILL.md. Use references for background documents, scripts for repeatable actions, and assets for reusable templates. A useful description tells the agent both what the skill does and when it applies.
Match the loading mechanism to the API
Agents API sessions discover skills from directories in their sandbox. Responses shell tools have their own upload, attachment, and versioning mechanism. Do not assume an uploaded Responses skill reference automatically becomes available in a managed agent session.
Review scripts and permissions
Treat skill content and scripts as code and instructions that need review. Limit access to the files and services the workflow actually requires. Test the workflow against expected outputs, including cases where the skill should not apply.
Read the official reference
Check the source for current API fields, account requirements, and service limits.
OpenAI: tools-skills