Skills in Responses (hosted shell attachments skill_reference / inline, local path skills)
Status: DOCUMENTED · LIVE_VERIFIED (2026-09-18, gpt-5.4-nano: skill created through /v1/skills, mounted in a shell container_auto environment, read by the model, echo OK executed)
Sources: https://developers.openai.com/api/docs/guides/tools-skills · https://developers.openai.com/api/reference/resources/skills · openapi-master.yaml SkillReferenceParam, InlineSkillParam, InlineSkillSourceParam, LocalSkillParam, ContainerAutoParam.skills, CreateContainerBody.skills
Last verified: 2026-09-18 · API CRUD: Skills API
Skills are not a tool type: they are attachments of the shell tool's hosted environment (or of a container created via POST /v1/containers).
Attachment shapes
| Where | Shape | Notes |
|---|---|---|
tools[type=shell].environment (container_auto) .skills[] and POST /v1/containers .skills[] |
{"type":"skill_reference","skill_id":"skill_…","version":"<int>"|"latest"} |
omitted version → skill default_version; ≤ 200 skills |
| same | {"type":"inline","name","description","source":{"type":"base64","media_type":"application/zip","data":"<base64 zip>"}} |
data ≤ 70,254,592 chars |
tools[type=shell].environment (local) .skills[] |
{"name","description","path"} |
absolute paths in your runtime; skill_reference not accepted locally |
| Agents API sandboxes | capability directories (absolute, unique, no ./.., ≤ 32 per session) |
harness discovers SKILL.md |
Bundle rules (docs)
Exactly one SKILL.md/skill.md with frontmatter name + description (what it does and when to use it); ≤ 500 files per version; ≤ 25 MB uncompressed; supporting files linked from SKILL.md. The platform injects each skill's name, description, path into the user-prompt context; the model decides to read SKILL.md — instruct it explicitly ("use the <name> skill") for determinism.
Live evidence
Request: tools: [{"type":"shell","environment":{"type":"container_auto","skills":[{"type":"skill_reference","skill_id":"skill_…"}]}}], prompt "Use the atlas-hello skill: run echo OK".
Output sequence: reasoning → shell_call (commands: ["ls -R /home/oai/skills/atlas-hello-1", "cat /home/oai/skills/atlas-hello-1/SKILL.md"], environment: {type:"container_reference", container_id:"cntr_…"}) → shell_call_output (stdout shows SKILL.md) → reasoning → shell_call (["echo OK"]) → shell_call_output (stdout: "OK\n", outcome: {type:"exit", exit_code:0}) → message "OK". Mount path pattern: /home/oai/skills/<name>-<version>. Cost: one 1 GB container session ($0.03) + tokens.
Security (docs)
Inspect every skill (SKILL.md = prompt-injection vector, user-level priority); never let end users attach arbitrary skills from an open catalog; gate write/high-impact actions behind approvals; review the network Risks & safety section when combining skills with network_policy.allowlist.
Examples: examples/openai/tools/skills/ (API CRUD, sh/py/ts); hosted mount captured in tmp-live/tools/shell_hosted_skill.json (gitignored).