How to Use OpenAI Skills Safely

A reusable agent workflow can begin as a prompt, but repeated work soon exposes the limits of copying instructions between chats. Important steps get omitted, output formats drift, and the reasoning behind a process becomes difficult to review. An OpenAI skill addresses that problem by placing operational instructions and supporting materials in a structured folder that can be versioned and inspected.

That convenience should not be mistaken for a security boundary. A skill can influence which tools an agent selects, which files it reads, which scripts it runs, and which external services it contacts. Safe adoption therefore requires two kinds of review: evaluate the workflow as readable knowledge, and evaluate its possible actions as software supply-chain input.

This guide explains the format, its place inside OpenAI plugins, the real limits of portability, and a practical process for deciding whether a skill belongs in personal experimentation or an approved production environment.

Understand the unit you are installing

The open Agent Skills specification defines a skill as a directory centered on a SKILL.md file. That file uses YAML metadata for fields such as the skill name and description, followed by Markdown instructions. Optional directories can hold scripts, references, assets, templates, schemas, or other resources needed by the workflow.

This structure is deliberately modest. The name and description help a compatible agent discover when the skill may apply. The full instructions can be loaded when the workflow is activated, while larger supporting resources remain available until needed. This progressive loading makes it possible to keep many specialized procedures accessible without inserting every instruction into every conversation.

A skill is therefore more than a saved prompt. It can define inputs, ordered steps, required evidence, output constraints, failure conditions, and acceptance checks. A review skill might require framework detection, test execution, security checks, and a fixed report. A publishing skill might require complete metadata, verified sources, image provenance, and validation before release.

The format also separates general model capability from local procedure. Subject-matter experts can express judgment in readable instructions, while engineers can add deterministic scripts where exact behavior matters. Both parts can be reviewed in version control. The OpenAI Academy skills guidance presents this reuse as a way to stop explaining the same recurring process from scratch.

Treat discovery metadata as executable routing

The description in SKILL.md is not decorative copy. It often helps the agent decide whether the skill matches the current task. A description that is too broad can route unrelated work into the workflow; one that is vague can prevent activation when the skill is needed. Either failure can change the agent's behavior before a person sees the detailed instructions.

Review the name and description as carefully as the steps. They should state what the skill does, the situations that trigger it, and meaningful exclusions. If a workflow edits spreadsheets but should not control a live Excel session, that boundary belongs in the discovery language. If it may publish content only after explicit approval, that condition must be unmistakable.

Then inspect the instruction hierarchy. A skill does not gain authority merely because it activates. User intent, platform policy, sandbox restrictions, project rules, and approval requirements still apply. Instructions that tell the agent to ignore those controls are a reason to reject the package, not a shortcut around them.

Separate a skill from its plugin container

OpenAI's original skills catalog is deprecated and directs developers toward current plugin examples and guidance. This is a distribution change, not evidence that the underlying skill format has disappeared. The core instructional unit can remain a SKILL.md folder, while the installable product becomes a plugin.

According to OpenAI's plugin packaging guide, a plugin has a required .codex-plugin/plugin.json manifest at its root. The package can include skills alongside MCP server definitions, apps, commands, hooks, agent metadata, and assets. A skill-only plugin is still possible when instructions and bundled resources are sufficient.

The distinction is useful when setting scope. A skill describes a repeatable procedure. A plugin can deliver the broader capability needed to distribute and operate that procedure, including external tools, authentication requirements, interface elements, and package metadata. The plugin is the installation boundary; the skill remains one component within it.

For new OpenAI-focused distribution, follow the current plugin path instead of building an installation process around the deprecated catalog. Preserve the workflow itself in a standards-compatible skill wherever practical. This keeps durable instructions distinct from host-specific integration and makes later review or migration easier.

Be precise about portability

Plain Markdown, a small required schema, and optional resource folders make skills easier to move between compatible agents. The specification supplies a common layout, and readable files work well with familiar version-control and code-review practices. That is meaningful portability at the instruction layer.

It is not a guarantee that the same folder will behave identically everywhere. Hosts may interpret optional metadata differently. Tool names, operating systems, dependencies, filesystem paths, connectors, context limits, and approval flows can vary. A workflow that invokes a local command will not automatically function in a browser-only environment. A workflow that needs private data will fail without an available connector and suitable authorization.

Evaluate portability in layers:

1. Core procedure: Can another compatible host understand the goals, sequence, inputs, and output contract?
2. Bundled resources: Are file references relative, documented, and available with the skill?
3. Runtime assumptions: Are commands, packages, operating-system requirements, and failure messages explicit?
4. Connected actions: Which tools, authentication methods, and interfaces are specific to one host or plugin?
5. Behavioral results: Does the workflow activate and complete representative tasks consistently in each intended environment?

A good design keeps durable procedure in the skill and places product-specific connectors, interface metadata, permissions, and installation behavior in the surrounding package. This does not make every action portable, but it prevents incidental integration details from obscuring the reusable knowledge.

Review permissions by consequence, not file type

Readable Markdown is easier to inspect than an opaque binary, but instructions can still cause consequential tool use. The relevant question is not simply whether the package contains code. Ask what it can persuade or instruct the agent to do.

Map every requested capability to a concrete step. File read access may be necessary for document analysis, but broad write access is not. Network access may be justified for a research workflow, while access to credentials or unrelated services is not. A tool that can send messages, publish content, change production systems, or delete data deserves an explicit confirmation boundary.

Scripts need direct inspection. Check every executable and supporting file, not only SKILL.md. Identify commands, dependencies, environment variables, network destinations, file paths, and any operation that changes external state. Prefer the smallest permission set that completes the intended task, and test with disposable data or a sandbox before allowing access to valuable systems.

Also examine indirect inputs. References, fetched pages, and connected data can contain instructions of their own. A safe workflow should treat those materials as content to analyze, not as higher-priority authority. Package instructions should state where untrusted content enters and how the agent must handle it.

Manage skills as supply-chain dependencies

A public repository's popularity is not evidence of security review, production reliability, or successful adoption. A malicious or compromised skill can attempt to obtain secrets, alter files, contact an unexpected service, or widen its scope through scripts and references. A benign workflow can become risky after an update or grow stale when an API, product interface, or compliance rule changes.

Record provenance before installation: publisher, repository, exact revision or version, license, review date, and approved files. Pin the reviewed revision when the installation method permits it. Do not accept an update merely because it is newer; inspect the diff, rerun evaluation cases, and reassess any permission changes.

Lifecycle signals matter too. The old OpenAI skills repository remains accessible even though its notice says it is deprecated. Search results and saved links can outlive the preferred installation route. Check the repository notice and current documentation rather than assuming a reachable package is still maintained. Define how a team will disable, replace, or roll back a skill if its source is compromised or its behavior changes.

For organizational use, ownership must be explicit. Someone should be responsible for updates, compatibility, test cases, and retirement. Store the approved package in a controlled location, keep an audit trail, and separate experiments from the set that agents may activate in production work.

Run a staged evaluation before approval

A valid directory only proves that files are arranged correctly. It does not show that activation is reliable, instructions are safe, or results are useful. Use a staged evaluation with representative tasks and clear pass conditions.

1. Establish purpose and boundaries

Write down the recurring task, intended users, accepted inputs, expected outputs, and actions that must remain out of scope. Decide whether better instructions are sufficient or whether the workflow truly needs a plugin with tools and connected services. Start with the smallest capability that solves the problem.

2. Audit every package component

Read the manifest, SKILL.md, scripts, references, assets, and configuration. Verify that links and dependencies match the stated purpose. Search for secret access, destructive commands, unexpected network calls, absolute local paths, hidden downloads, and instructions that bypass approval or policy.

3. Build an explicit permission map

List each tool and data source, the operation it enables, whether access is read-only or mutating, and when human confirmation is required. Remove capabilities with no matching workflow step. Use limited credentials and sandboxed resources during evaluation.

4. Test routing and normal behavior

Create representative tasks that should trigger the skill and nearby tasks that should not. Check whether the description routes work correctly. For positive cases, verify required steps, evidence, output format, and acceptance checks rather than judging only whether the final answer sounds plausible.

5. Test failure and refusal behavior

Try missing inputs, unavailable tools, invalid files, conflicting instructions, and requests beyond scope. The skill should stop clearly, preserve data, and request the necessary decision instead of improvising authority. Confirm that untrusted content cannot silently redefine the workflow.

6. Test portability where it is claimed

Run the same cases in every intended host. Record which parts of the core instructions transfer and which integrations require adaptation. Do not label a complete plugin portable when only its inner skill is standards-compatible.

7. Approve a revision and monitor change

Pin the evaluated version, record results and known limitations, name an owner, and set a review interval. Re-evaluate after changes to instructions, scripts, permissions, dependencies, tools, or host behavior. Keep a rollback path and a clear retirement process.

Use the smallest trusted layer

Skills are valuable because they make recurring operational knowledge visible, reusable, and reviewable. Plugins add a practical delivery layer when the workflow needs installation metadata, tools, authentication, interfaces, or organizational controls. Neither layer is safe by default, and neither removes the need for host-enforced permissions.

The durable approach is to keep core procedure readable, isolate product-specific integrations, grant only the access each step requires, and test behavior rather than syntax alone. When provenance, permissions, evaluation cases, ownership, and rollback are documented together, a skill becomes a governed workflow instead of an unexamined instruction bundle.