# 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](../../openai/skills-api.md)

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).