Why OpenAI’s Skills, Shell, and Compaction Are Redefining AI Agent Engineering

Core primitives

Skills

Skills are versioned SKILL.md packages that follow the Agent Skills open standard. Each package contains a description, pre‑conditions, and executable code. When a skill is mounted, the model sees its name, description, and path, and can retrieve the full SKILL.md file to follow a concrete procedure.

Shell

The upgraded Shell tool provides a controlled container hosted by OpenAI. It allows agents to install dependencies, run scripts, read/write files, and produce artifacts (e.g., reports). Developers can also run a local Shell runtime with identical semantics; both modes expose results through the Responses API.

Compaction

Long‑running workflows quickly hit the model’s context window. Server‑side Compaction automatically compresses the conversation history when the limit is reached, ensuring uninterrupted execution and reducing token costs. An explicit endpoint /responses/compact is also available for manual control.

Practical patterns and tips

Write skill descriptions as routing logic, not marketing copy. Include when to use the skill, when not to use it, and clear success criteria (a "use case vs. disabled case" block).

Provide negative examples and edge‑case scenarios to reduce accidental triggers.

Embed templates and example data inside the skill package so they are loaded only when the skill is invoked, saving tokens.

Design for long‑running execution from the start: reuse the same container for stable dependencies, pass previous_response_id between steps, and enable Compaction as the default context‑management strategy.

When deterministic behavior is required, explicitly command the model to use a specific skill with syntax <skill name> to create a reliable execution contract.

Treat "Skills + network access" as a high‑risk combination. Use strict whitelist policies and assume tool output is untrusted.

Use /mnt/data as the standard artifact hand‑off directory for hosted Shell workflows.

Understand the two‑layer network whitelist: an organization‑level whitelist set by admins, and a request‑level whitelist that must be a subset of the organization whitelist.

Authenticate API calls with domain_secrets so the model only sees placeholders (e.g., $API_KEY) and the sidecar injects real values at request time.

Skills work with both hosted and local Shell. Invoke the local Shell via shell_call and retrieve the result with shell_call_output. Custom Shell executors can be added via the Agents SDK.

Recommended development loop:

Iterate locally for rapid debugging and easy access to internal tools.

When reproducibility, isolation, or deployment consistency is needed, migrate to a hosted container.

Keep skill packages unchanged across environments so the workflow remains stable.

Three build modes

Mode A – Install → Fetch → Write artifact

Use the hosted Shell to install dependencies, retrieve external data, and write the result to an artifact such as /mnt/data/report.md. This creates a clear review boundary for logs, diffs, and downstream steps.

Mode B – Skills + Shell for repeatable workflows

Encode the workflow (steps, guards, templates) into a skill, mount the skill in a Shell environment, and let the agent deterministically generate artifacts. Typical use cases include spreadsheet analysis, dataset cleaning, and periodic report generation.

Mode C – Skills as enterprise workflow carriers

Skills provide a programmatic reasoning layer without inflating the system prompt, bridging the gap between single‑tool calls and multi‑tool orchestration. In a Glean case study, a Salesforce skill raised accuracy from 73 % to 85 % and cut first‑token latency by 18.1 % through precise routing, negative examples, and embedded templates.

One build, run anywhere

Combine Skills (declarative procedures), Shell (execution engine), and Compaction (context management) to build agents that can run for extended periods, handle real files, and stay within token limits. Recommended practice: start locally, then move to hosted containers for production, while always using organization‑ and request‑level network whitelists and domain_secrets for secure authentication.

Comparison with OpenClaw

Architecture : OpenAI provides a hosted, sandboxed container; OpenClaw is self‑hosted on the user’s machine or cloud VM.

User entry : OpenAI targets developers via API/CLI; OpenClaw integrates with chat platforms (WhatsApp, Telegram, Discord) for direct bot control.

Security : OpenAI offers strong isolation; OpenClaw grants full host shell permissions, raising higher risk.

Context management : OpenAI uses automatic server‑side compaction; OpenClaw relies on local persistence or vector memory.

Typical use cases : OpenAI suits large‑scale data analysis, SaaS integration, and enterprise automation; OpenClaw excels at personal file management, local automation, and cross‑platform messaging.

Glean’s experience: initial skill routing reduced trigger rate by ~20 %, but adding negative examples and edge‑case coverage restored it.

Reference: https://developers.openai.com/blog/skills-shell-tips