
OpenAI Agent Engineering Guide: 10 Practical Tips and 3 Construction Patterns
OpenAI has released a practical handbook for Agent engineering: how to use the three API capabilities of Skills, Shell tools, and Context Compaction to keep agents running for long periods without crashing.
This is an article from OpenAI's official developer blog, with the motivation of promoting the Responses API. However, the techniques themselves are quite practical, especially the production case data from the enterprise AI search company Glean (valued at $7.2 billion). However, the Agent Skills open standard mentioned was actually initiated by Anthropic at the end of 2025, with OpenAI being an adopter. The standardization of the agent toolchain is progressing across companies.
The full article has three parts: mental models for three concepts, 10 practical tips, and 3 construction patterns.
A Simple Mental Model
Skills: The "Operation Manual" the Model Loads on Demand
A skill is a set of files plus a SKILL.md manifest, which contains frontmatter metadata and instructions. Think of it as a version-controlled operation manual that the model consults when it needs to work.
The platform exposes each skill's name, description, and path to the model. The model uses this metadata to decide whether to invoke it. If invoked, it reads SKILL.md to get the complete workflow.
Note: Agent Skills is an open standard, first released by Anthropic at the end of 2025. It has since been adopted by over twenty AI tools, including OpenAI Codex, GitHub Copilot, Cursor, and Google Gemini CLI. The core idea is "progressive disclosure": the model first sees the skill's metadata, and only loads the full instructions if it deems it necessary, avoiding wasted tokens.
Shell Tool: The Agent's "Execution Environment"
The Shell tool allows the model to work in a real terminal environment. Two modes:
The hosted Shell goes through the Responses API, with requests carrying stateful work, tool calls, multi-turn continuations, and artifacts.
Context Compaction: Keeping Long Conversations Going
As workflows get longer, you'll eventually hit the context window wall. Server-side compaction solves this by automatically managing the context window and compressing conversation history.
The Responses API offers two methods:
Among the three capabilities, Compaction might be the most directly valuable for developers. Manually managing the context window has always been a pain point for long-running agents. The previous common practice was to brutally truncate history, but this often cut off key information the agent was reasoning about mid-step. Automatic compaction retains key context and discards noise, which is a much better approach than truncation.
Early data from e-commerce platform Triple Whale showed that their agent Moby maintained accuracy throughout a session involving 5 million tokens and 150 tool calls.
Why the Three Work Better Together
The combination: repeatable workflows with real execution power, instead of stuffing system prompts into a fragile, massive document.
Many teams now have system prompts ballooning to tens of thousands of tokens, mixing role settings, workflows, format requirements, and safety rules, making maintenance a mess. The Skills approach breaks these into independent modules, loaded on demand.

10 Practical Tips
Tip 1: The Skill's Description is the Model's Decision Boundary
The skill description should answer three questions: When should it be used? When should it not be used? What are the output and success criteria?
A practical approach: directly include "used for vs. not used for" blocks in the description, keeping it specific (input, tools involved, expected output).

Tip 2: Add Negative Examples and Edge Cases to Reduce False Triggers
An unexpected failure mode: providing a skill actually lowers the correct trigger rate. An effective fix is to add negative examples and edge case coverage.
Write a few clear lines about "do not call this skill in these situations" (and what to do instead) to help the model route more cleanly, especially when there are multiple skills that look very similar.
Glean encountered this problem: skill-based routing initially caused a ~20% drop in trigger rate in targeted evaluations. It recovered after adding negative examples and edge case coverage.
When faced with multiple skills, the model's decision difficulty is similar to a human's: the more options, the more hesitation. Clearly stating "this is not what you want" helps decision-making more than just saying "this is what you want."

Tip 3: Put Templates and Examples in Skills (They Cost Almost No Tokens When Not Used)
If you've been stuffing templates into system prompts, stop doing that.
Putting them in skills has two benefits: they are loaded only when needed (when the skill is invoked), and they don't increase token consumption for unrelated queries.
This is particularly effective for knowledge work outputs: structured reports, escalation triage summaries, customer proposals, data analysis reports.
Glean reported that this pattern brought them the biggest quality and latency improvements in production, because examples are only loaded when the skill is triggered.

Tip 4: Design for Long-Running Operation from the Start
Long-running agents are rarely handled by a one-shot prompt. Plan for continuity from the beginning:
This combination reduces restart behavior and keeps multi-step tasks coherent as the thread grows.

Tip 5: When Determinism is Needed, Tell the Model Which Skill to Use Directly
The default behavior is for the model to decide when to use a skill, which is often what you want.
But in production workflows with clear contracts, prefer determinism over intelligence, and directly say "use the XX skill." This is the simplest reliability lever you can pull, turning fuzzy routing into a clear contract.
The model's autonomous judgment is an advantage in flexible scenarios, but a risk in pipeline scenarios. Knowing when to let go and when to take back control is key to building reliable agents.

Tip 6: Skills + Web = High-Risk Combination
Combining skills with open web access creates a high-risk path for data leakage. If you use the web, keep the whitelist strict, assume tool outputs are untrusted, and avoid the "open web + powerful operations" combination in consumer-facing workflows.
Reasonable default configuration:

Tip 7: Use /mnt/data as the Handoff Boundary for Outputs
In hosted Shell workflows, use /mnt/data as the standard location for writing outputs. Write all deliverables here for subsequent retrieval, review, or passing to the next step: reports, cleaned datasets, completed spreadsheets.
A useful mental model: tools write to disk, the model reasons about the content on disk, and the developer retrieves it from disk.

Tip 8: The Whitelist is a Two-Tier System
Network control has two tiers:
The organization whitelist should be small and stable, the set of "approved targets" you trust. The request whitelist should be even smaller, containing only the targets needed for that specific task. Including domains outside the organization whitelist in a request will result in an immediate error.

Tip 9: Use domain_secrets for Authenticated Calls
When domains in the whitelist require authentication headers, use domain_secrets. The model never sees the real credentials.
At runtime, the model sees placeholders (like $API_KEY), and a sidecar process injects the real values only for approved targets. This is a good default practice when an agent calls a protected API from within the container.

Tip 10: Use the Same API for Cloud and Local
You don't have to host everything: skills work in both hosted and local Shell modes; Shell has a local execution mode where you execute shellcall yourself and return shellcall_output; if using the Agents SDK, you can also plug in your own executor.
A practical development loop: start locally (fast iteration, easy debugging) → switch to the hosted container (when repeatability and isolation are needed) → skills remain unchanged in both modes, the execution environment changes, but the workflow stays the same.

Three Construction Patterns
Pattern A: Install → Fetch → Write Output
The simplest use of the hosted Shell: the agent installs dependencies, fetches external data, and generates deliverables. For example, install a few libraries, fetch data or call an API, and write a report to /mnt/data/report.md.
This pattern establishes a clear review boundary: the application can display the output to the user, log it, diff it, or pass it to subsequent steps.

Pattern B: Skills + Shell for Repeatable Workflows
After building one or two successful Shell workflows, the next question arises: they work, but reliability drops as soon as the prompt drifts.
Skills are designed for this scenario:
This is particularly effective for spreadsheet analysis and editing, data cleaning with summary generation, and standardized report generation for repetitive business tasks.

Pattern C (Advanced): Skills as Enterprise Workflow Carriers
An early observation: there is a steep accuracy drop-off between "single tool invocation" and "multi-tool orchestration." Skills fill this gap by making tool reasoning more procedural without bloating system prompts.
Glean's case: a Salesforce-oriented skill improved evaluation accuracy from 73% to 85%, with a 18.1% reduction in first-byte latency. Practical strategies include fine-grained routing, negative examples, and embedding templates and examples within skills. Glean also uses skills to encode repetitive tasks in enterprise workflows: customer solution planning, escalation triage, and brand-aligned content generation.
This is the form where skills demonstrate their power: living Standard Operating Procedures (SOPs) that evolve with the organization and are executed consistently by agents.
The improvement from 73% to 85% is significant, but the article does not disclose the evaluation benchmark or sample size. The "18.1% reduction in first-byte latency" also lacks absolute values. The direction of the numbers is correct, but the precision is questionable.

Final Thoughts
As an official practical guide from OpenAI, most of the 10 tips can be applied directly. The most valuable insights are "skill descriptions are decision boundaries" and "negative examples improve routing accuracy," which are relevant for any developer building multi-skill agents.
Information readers need to supplement on their own: the Agent Skills standard was initiated by Anthropic, with OpenAI being one of the adopters; the article does not mention costs at all; hosted containers and Compaction are proprietary capabilities of the OpenAI platform and should not be confused with "open standards."
Skills, as a cross-platform open standard, are being adopted simultaneously by mainstream AI tools such as Claude Code, GitHub Copilot, Cursor, and OpenAI Codex. An agent's capabilities no longer rely solely on the model's intelligence but also on modular "process knowledge."