2026 Comparative Analysis: Agent Skills Packaging and Portability Infrastructure — Applied Technology Index

Executive Summary

An Agent Skill is a directory that packages reusable instructions, metadata and optional scripts, references and assets around a required SKILL.md file. The open Agent Skills specification standardizes the smallest useful interchange format: a YAML frontmatter contract for discovery, a Markdown body for instructions and directory conventions for resources. It does not standardize a registry, dependency resolver, signature system, permission model, sandbox, update protocol, evaluation result or execution receipt.

The format has moved beyond one vendor. Public documentation available on 8 August 2026 identifies support in Anthropic Claude products, OpenAI ChatGPT and Codex, GitHub Copilot and Visual Studio Code, and Google Gemini CLI. These systems agree on the core progressive-disclosure pattern: load name and description into the initial catalog, load the SKILL.md body when the skill is selected, and access supporting files only when needed. That common shape makes procedural knowledge more portable and context-efficient than copying large prompts into every session.

The central finding is that format portability is not execution portability. A conforming skill can move between hosts as readable instructions, but observable behavior still depends on host-specific discovery paths, precedence rules, tool names, approval policy, filesystem layout, network access, installed runtimes, model behavior and proprietary metadata. The base specification’s allowed-tools field is experimental, and host extensions differ. OpenAI uses agents/openai.yaml for invocation policy and tool dependencies. VS Code adds fields including user-invocable, disable-model-invocation and experimental forked context. Anthropic’s API turns uploaded skills into workspace-scoped, versioned resources executed in a managed code-execution container. Gemini CLI requires an activation confirmation before adding the skill directory to allowed file paths.

Skills occupy a different layer from tools and protocols. A skill teaches an agent how to perform a workflow; MCP or native tools provide operations the agent can invoke; AGENTS.md and custom instructions provide persistent repository guidance; plugins and extensions provide distribution and integration packaging. A production skill may reference tools, but possession of the skill must not grant ambient authority to those tools.

The primary operational risk is that a skill is executable content disguised as documentation. Its Markdown can redirect agent behavior, its references can contain prompt injection and its scripts can execute with the host’s credentials and filesystem access. GitHub explicitly warns that downloaded skills are not verified and may contain malicious scripts or hidden instructions, and warns against pre-approving shell access without review. Gemini CLI makes activation and installation consent visible. The open client implementation guide advises trust-gating project skills because a newly cloned repository can otherwise inject instructions into an agent’s context.

For operators, the recommended architecture is a governed skill supply chain: store source in version control; validate the format; pin an immutable commit or content digest; scan instructions, scripts and transitive dependencies; declare compatibility and tool requirements; install into explicit scopes; keep shell and network privileges separate from skill activation; test selection and outcomes across supported models; and record the exact skill digest, host, model, tools, policy and result for every consequential run. Treat skills as versioned software packages, not trusted prompts.

Key Findings

• The portable core is deliberately narrow. The specification requires only name and description in YAML frontmatter plus a Markdown body. license, compatibility, metadata and experimental allowed-tools are optional.
• Progressive disclosure is the common architectural contract. Metadata is catalogued first, instructions are loaded on activation and resources are read or executed later. This reduces context cost but makes selection quality depend heavily on the description.
• Selection is probabilistic unless invocation is explicit. Hosts generally let the model match a task to a description; OpenAI, VS Code and other interfaces also expose explicit mentions or slash commands. A valid skill can still be missed, over-triggered or shadowed.
• .agents/skills/ is the strongest cross-client placement convention, not part of the file-format specification. OpenAI Codex, GitHub Copilot, VS Code and Gemini CLI document this location, while supporting additional vendor-specific paths.
• Collision behavior is not portable. The open implementation guide recommends deterministic precedence with project scope overriding user scope. Gemini CLI defines its own ordered tiers. OpenAI Codex documents that same-name skills are not merged and both may appear.
• Host extensions create useful but non-portable behavior. Invocation controls, UI fields, dependencies, forked execution and managed version IDs may be ignored by another client even when the base skill loads.
• Skills are not tool capabilities. A workflow description can request shell, MCP or API operations, but the host’s authorization, approval, sandbox and network policy must remain authoritative.
• Skills are a software supply-chain surface. Installation can introduce executable scripts and model instructions. Validation checks structure, not intent, safety or correctness.
• Versioning remains fragmented. Anthropic exposes managed skill versions; GitHub CLI can install by tag or SHA, pin versions and record source metadata; local directory discovery often reads mutable files directly.
• A successful load is not a quality result. Teams need trigger tests, task-output evaluations, negative security tests and cross-host conformance tests in addition to frontmatter validation.

Methodology

This analysis reviewed the live Applied Technology Index research index and local public content collection before topic selection to avoid duplicate coverage. Current technical activity around SKILL.md, cross-client skill directories and newly documented host support was used as a discovery signal. The Agent Skills specification repository showed active maintenance through 4 August 2026, and Visual Studio Code’s public Agent Skills page was dated 5 August 2026. Social and search chatter was not used as evidence for product capabilities.

Substantive claims are grounded in the open Agent Skills specification and client-implementation guide; official Anthropic, OpenAI, GitHub and Visual Studio Code documentation; and the public Gemini CLI repository documentation available on 8 August 2026. The comparison applies ten criteria:

1. Portable format: required frontmatter, body and directory conventions.
2. Discovery scope: project, user, administrator, built-in, extension or managed workspace locations.
3. Precedence and collision handling: which skill wins when names overlap.
4. Activation: implicit model selection, explicit user invocation and consent behavior.
5. Progressive disclosure: when metadata, instructions and resources enter model context.
6. Execution environment: local host, cloud agent, sandboxed container or host-dependent runtime.
7. Distribution and versioning: filesystem copy, Git repository, CLI installer, plugin, extension or managed API object.
8. Permission boundary: treatment of scripts, shell, network, filesystem and referenced tools.
9. Host extensions: fields and behaviors outside the portable core.
10. Governance evidence: validation, provenance, pinning, review and auditable execution.

This is a documented-capability and architecture comparison, not a benchmark. No identical skill was executed across every host, and no vendor’s cloud environment, extension marketplace, installer or permission system was penetration-tested. Product documentation can describe different surfaces under one brand; for example, local Claude Code skills and Claude API managed skills have materially different lifecycle controls.

Comparative Analysis Table

Observed Profiles

Agent Skills specification: a thin interchange contract

The open specification defines a skill as a directory containing a required SKILL.md. The file begins with YAML frontmatter and continues with unrestricted Markdown instructions. name and description are required. Names are limited to 64 lowercase alphanumeric or hyphen characters, cannot start or end with a hyphen, cannot contain consecutive hyphens and must match the parent directory. Descriptions are limited to 1,024 characters and are expected to state both capability and trigger conditions.

Optional frontmatter includes license, compatibility, arbitrary string-to-string metadata and experimental allowed-tools. The directory may contain any additional files, with scripts/, references/ and assets/ documented as common conventions rather than an exhaustive schema. This openness is useful: a skill can package deterministic utilities, domain references, forms, templates or datasets without placing all of them in the model’s initial prompt.

The specification recommends three disclosure tiers. Roughly 100 tokens of metadata per skill can be available at startup; the full SKILL.md, recommended below 5,000 tokens and 500 lines, loads on activation; resources load as needed. Relative file references are resolved from the skill root. A reference validator checks naming and frontmatter rules.

What the validator cannot establish is equally important. It does not prove that a description triggers reliably, that instructions are non-malicious, that a script is deterministic, that declared dependencies exist, that a referenced binary is safe, that the skill has permission to perform a task or that two clients produce equivalent outputs. The portable object is an instruction package, not a certified capability.

The client-implementation guide fills in operational behavior without making it part of the core file format. It recommends scanning project and user scopes, including .agents/skills/, applying deterministic collision rules, exposing a compact catalog to the model and loading the body through file access or a dedicated activation tool. It specifically notes that project-level skills can come from untrusted repositories and should be gated on folder trust. This is a critical boundary because discovery itself can become instruction injection.

Anthropic: filesystem skills plus managed API objects

Anthropic documents Agent Skills across Claude Code, claude.ai and the Claude API. All use the same conceptual package but not the same deployment model. Claude Code discovers filesystem skills under personal or project paths. claude.ai accepts custom skills through product settings. The API exposes workspace-wide custom skills as managed objects with identifiers, source labels, timestamps and version identifiers.

In the API, a request supplies skills in the Messages API container parameter and can choose latest or a specific version. Skills require Anthropic’s code-execution tool and the documented Skills beta header. File input and output use the Files API when needed. Anthropic’s guide documents a maximum of eight skills per request and distinguishes Anthropic-maintained document skills from custom workspace skills.

The managed execution environment materially changes the risk model. Anthropic documents that API skills run in a sandboxed container with no network access and no runtime package installation. This constrains data exfiltration and dependency drift compared with unrestricted local shell execution, although uploaded instructions and code can still mishandle provided files, produce misleading outputs or exploit available runtimes.

Anthropic’s authoring guidance also sharpens an important reliability point: skill behavior depends on the underlying model. Teams are told to test across every model they plan to use and to calibrate instruction freedom to task fragility. That means a skill version alone is not a reproducible execution identity. The model, host runtime, tool versions and policy must also be pinned or recorded.

OpenAI: a shared authoring format with a separate plugin distribution layer

OpenAI documents skills as reusable workflows for ChatGPT and Codex and explicitly states that they build on the open Agent Skills standard. Both implicit selection and explicit invocation are supported. ChatGPT can select a skill through @; Codex can use /skills or $ mentions. The description remains the matching surface for implicit activation.

Codex’s catalog has a documented budget: the initial skill list uses at most two percent of the model context window, or 8,000 characters when the window size is unknown. Descriptions can be shortened, and some skills can be omitted when the collection is large. This turns catalog scale into a measurable selection constraint. Operators cannot assume that installing hundreds of skills leaves discovery unchanged.

Local Codex discovery covers .agents/skills from the current directory through repository ancestors, a user scope, an administrator scope and OpenAI-bundled system skills. Same-name skills are not merged and can both appear, so name uniqueness and explicit selection matter. OpenAI also supports disabling a local skill through configuration.

For broader distribution, OpenAI separates skills from plugins. A skill authors the workflow. A plugin can distribute multiple skills and optionally bundle MCP connections, connector configuration and presentation assets. This is more complete as a product package but less portable than the base directory alone.

OpenAI’s optional agents/openai.yaml illustrates the extension pattern. It can define interface metadata, prevent implicit invocation and declare tool dependencies such as an MCP server. Another client may ignore this file. A cross-client skill should therefore remain useful from the base SKILL.md, while host adapters add convenience rather than silently carrying essential safety controls.

GitHub Copilot and VS Code: broad surfaces, CLI provenance and explicit script warnings

GitHub documents Agent Skills across Copilot cloud agent, code review, Copilot CLI, the Copilot app, VS Code and JetBrains agent mode. Project paths include .github/skills, .claude/skills and .agents/skills; personal paths include Copilot-specific and .agents locations. This path compatibility makes GitHub’s implementation practical in mixed-agent repositories.

The strongest distribution controls in the reviewed public documentation are in the preview gh skill workflow. Users can search, preview without installing, install from a GitHub repository, select a tag or commit SHA, pin a version, update installed skills and publish after validation. Installation records source repository, ref and tree SHA in frontmatter so later updates can identify upstream changes. These controls improve traceability but do not turn a GitHub repository into a trusted registry.

GitHub is explicit about that distinction: skills are not verified and can contain prompt injections, hidden instructions or malicious scripts. It recommends gh skill preview before installation. When allowed-tools pre-approves shell or bash, GitHub warns that confirmation is removed and attacker-controlled skills or prompt injection may execute arbitrary commands. This is the correct threat model for any host, even when another vendor’s documentation is less direct.

VS Code adds richer interaction fields outside the base specification. user-invocable controls slash-menu visibility. disable-model-invocation can require explicit use. An experimental context: fork mode executes the skill in a dedicated subagent context and returns only the final result to the parent. Forking can reduce context pollution, but it is not a security sandbox: the subagent still needs separately enforced tools, filesystem paths, network policy and approval rules.

VS Code extensions can contribute skills through chatSkills, while OpenAI plugins and Gemini extensions use different package layers. The same SKILL.md can remain portable, but the installation, namespace, UI and dependency systems do not converge merely because the inner directory does.

Gemini CLI: deterministic precedence and activation consent

Gemini CLI documents four discovery tiers from lowest to highest precedence: built-in, extension, user and workspace. It supports Gemini-specific directories and .agents/skills aliases. When names collide, the higher-precedence scope wins; within user or workspace scope, .agents/skills takes precedence over the Gemini-specific directory. This is deterministic but differs from Codex’s documented behavior of keeping same-name skills visible.

Activation is unusually explicit. Gemini matches the task to skill metadata, calls activate_skill, shows the user the skill name, purpose and directory path, and only after approval injects the body and directory structure into conversation history and adds the skill directory to allowed file paths. This consent step gives users a meaningful boundary between catalog discovery and resource access.

Gemini CLI can list, link, enable, disable and reload skills. Its terminal tooling can install a skill from Git or a local directory, and its creation utilities can initialize, validate and package a .skill ZIP. The creation guide documents that the full directory becomes available on activation and that scripts can be run as part of the procedure.

Consent should not be confused with verification. A user may not inspect every reference or script before accepting. A safe installer should preview changed files, pin source identity, scan executable content and show requested tool classes before activation. Runtime approvals should still apply when an activated skill requests shell, network or destructive operations.

Portability Boundaries

Metadata compatibility

A portable skill should keep required behavior in standard fields and Markdown. Vendor metadata can improve UX but should fail safely when ignored. Do not rely on allowed-tools, agents/openai.yaml, VS Code invocation fields or Gemini-specific scope settings to enforce a security property on another host.

Tool-name compatibility

Instructions such as “call summarize_job_log_failures” assume a particular tool inventory. Another host may expose a differently named MCP tool, a native API or no equivalent capability. Portable skills should describe required capability and expected input-output shape, then isolate host bindings in small adapter references when possible.

Runtime compatibility

Bundled Python, JavaScript or shell code is not automatically portable. The compatibility field can document required runtimes, binaries, operating systems and network access, but the standard does not resolve or install them. Scripts should check prerequisites, fail with actionable errors and avoid implicit package installation.

Permission compatibility

A skill’s requested tools are not a grant. Hosts differ in shell confirmation, allowed filesystem paths, sandboxing, network access and managed credentials. The least common safe contract is instruction-only activation followed by normal host authorization for every capability.

Selection compatibility

Descriptions are model-facing classifiers. Hosts may truncate catalogs, omit skills, use different models or rank collisions differently. Test true-positive triggers, true negatives, ambiguous neighboring skills and explicit invocation on each supported host. Do not infer portability from successful validation alone.

Version compatibility

A mutable directory path or latest identifier prevents deterministic reproduction. Pin a Git SHA, managed version ID or content digest in production. Record the host version and adapter metadata because the same files may activate or execute differently after a client update.

Production Governance Model

1. Intake as untrusted software

Preview the entire directory before installation. Reject path traversal, hidden binaries, unexpected symlinks, generated archives, credential files and scripts that fetch or execute mutable remote content. Review Markdown for instructions that override user intent, disable safety controls, expose secrets or hide actions.

2. Verify source and immutable identity

Record source repository, commit or tag, tree or archive digest, author or publisher identity, license and review decision. Tags are convenient but can be moved unless protected; a commit SHA or content digest is the stronger execution reference. Preserve the reviewed package rather than downloading it again at run time.

3. Separate activation from authority

Activation may load instructions and references. It should not automatically grant shell, network, write, credential or production access. Resolve requested operations through the host’s ordinary policy engine, approvals and sandbox. Treat experimental pre-approval metadata as a local optimization, never a portable trust claim.

4. Constrain scripts

Prefer instruction-only skills when deterministic code is unnecessary. For scripts, use a sandbox, read-only mounts by default, explicit writable directories, network deny-by-default, short-lived credentials, resource limits and command allow-lists. Pin dependencies and scan them through the same software supply-chain controls used for application code.

5. Test selection and output

Maintain an evaluation set with prompts that should activate the skill, prompts that should not, adversarial documents, missing dependencies, malformed inputs and expected outputs. Run the set across supported hosts and models. Measure activation precision and recall, task completion, unsafe-action attempts, approval frequency and regression after skill or host updates.

6. Record execution evidence

For consequential runs, retain user request, selected skill name and digest, host and model versions, loaded references, invoked scripts, tools and arguments, approvals, policy version, outputs and errors. A chat transcript alone may omit filesystem reads, shell effects or installer provenance.

7. Promote through controlled scopes

Use personal scope for experimentation, project scope for reviewed repository workflows and administrator or managed workspace scope for organization-approved packages. Promotion should require validation, security review, evaluation evidence and an owner. Workspace precedence should not let an unreviewed repository silently shadow an approved organization skill.

8. Revoke and update deliberately

Maintain an inventory of installed skill versions and hosts. Support disabling by digest, removing compromised versions and identifying affected runs. Updates should present diffs and re-run evaluation; automatic replacement of reviewed code with an unreviewed upstream version defeats pinning.

Procurement and Deployment Implications

Ask whether “Agent Skills support” means format parsing or a governed lifecycle. A client may read SKILL.md correctly while lacking source preview, pinning, collision diagnostics, organization policy, revocation or run receipts.

Test cross-client claims with one real package. Install the same skill under .agents/skills/ in each target host. Verify discovery, trigger behavior, relative references, scripts, approvals, collision handling, disable controls and audit output. Document host adapters rather than claiming universal equivalence.

Require explicit trust boundaries. Project repositories, user-installed skills, marketplace packages, built-ins and administrator-managed skills should not share one undifferentiated trust level. The UI and policy engine should expose source and scope at activation time.

Treat catalogs as capacity-limited. Progressive disclosure saves instruction tokens, but metadata still consumes catalog budget and model attention. Consolidate overlapping skills, write discriminative descriptions and monitor omitted or shadowed entries.

Prefer immutable deployment references. Anthropic managed versions, Git commit SHAs, GitHub CLI pins and content digests provide stronger rollback and incident analysis than latest or mutable folders. A version field written by the author is metadata, not proof of package identity.

Do not let portability erase environmental facts. Document required tools, runtimes, network destinations, secrets, write paths and expected side effects. A workflow that works in an unrestricted laptop shell may correctly fail in Anthropic’s no-network API container.

Keep skills and MCP governance connected but separate. A plugin may bundle a skill with an MCP connection, but workflow installation must not imply OAuth consent or tool authorization. Maintain independent inventories for instruction packages, tool servers, credentials and execution policy, linked by immutable identifiers.

Limitations

This analysis relies on public specifications, documentation and source repositories available on 8 August 2026. Agent Skills implementations are changing quickly. GitHub marks gh skill as public preview, the base specification marks allowed-tools experimental, and VS Code marks forked skill context experimental. Product behavior, supported fields and directory precedence may change after publication.

The reviewed systems expose different surfaces. Anthropic’s local Claude Code skills, claude.ai uploads and managed API skills do not have identical lifecycle or execution properties. OpenAI’s local Codex skills and plugin-distributed skills differ. GitHub Copilot spans cloud, code review, CLI and IDE environments. Gemini CLI is a local-agent host with extension packaging. The table compares their documented skill infrastructure, not overall model or product quality.

No common conformance package was executed across all systems. The analysis does not measure activation precision, token cost, latency, task success, script compatibility, enterprise availability, pricing, adoption or security incident rates. Host-specific limits not clearly documented in the reviewed sources are not inferred.

The Agent Skills client showcase indicates a broader ecosystem than the five implementation groups profiled here, but a showcase listing is not proof of full conformance. Support can range from basic parsing to managed distribution and governance. Each additional client requires direct verification.

Security guidance is architectural, not a claim that any reviewed provider is vulnerable or safe. Sandboxes, approvals, installer previews and source metadata reduce risk but do not prove benign behavior. Formal software-composition analysis, code review, organizational policy and legal review remain operator responsibilities.

References

1. Agent Skills: Format specification
2. Agent Skills: How to add skills support to an agent
3. Agent Skills specification repository
4. Anthropic: Agent Skills overview
5. Anthropic: Skill authoring best practices
6. Anthropic: Using Agent Skills with the API
7. Anthropic API: Create Skill
8. OpenAI: Build skills for ChatGPT and Codex
9. GitHub: About agent skills
10. GitHub: Adding agent skills for GitHub Copilot
11. Visual Studio Code: Use Agent Skills in VS Code
12. Gemini CLI: Agent Skills
13. Gemini CLI: Creating Agent Skills

Changelog

• 2026-08-08: Initial publication.

Corrections

No corrections have been issued for this document.