Skip to content
Agentic Engineering Fieldbook

Agent Skill Formats and Extensions

Observation date and maintenance

Section titled “Observation date and maintenance”

Observed on 2026-09-12.

Applicable surfaces: Agent Skills specification, OpenAI Tools and Skills documentation, Claude Skills product documentation, and the current OpenAI Codex report on Skills and prompts for GPT-6 Astra.

Maintenance state: maintained Field Note. Revisit when the Agent Skills specification changes package requirements, when major products change their Skill packaging or loading behavior, or when compatibility claims become testable across multiple hosts.

Current observation

Section titled “Current observation”

Skill formats are becoming a common way to package reusable task knowledge for agentic systems. The emerging shape is simple: a named bundle contains an entry document such as SKILL.md, plus optional supporting files such as examples, reference material, scripts, templates, or assets. A host can decide when to load that bundle into context or expose its supporting resources.

The Skill description is part of that loading decision. Treat it as routing metadata: it should say what kind of task the Skill handles and, where useful, what nearby tasks it does not handle. A broad description can cause false activation when a host presents many Skills, while an overly short one can make the right Skill undiscoverable. These are current host and model behaviors to measure, not a universal length rule.

That packaging is useful because it gives teams a reviewable artifact. Instead of hiding task instructions in scattered prompts, onboarding notes, notebooks, and scripts, the Skill can put the task intent, required knowledge, constraints, and examples in one versioned place. It also creates a natural boundary for testing: load this Skill, run these representative tasks, inspect these traces, and verify these outputs.

The risk is overclaiming. A Skill is not a worker, an authority grant, a sandbox, a dependency lockfile, or a guarantee that the model will use the instructions correctly. It is packaged context and optional supporting material. The host and the surrounding system still decide what enters the model context, which tools exist, which scripts may run, which external effects are allowed, and which outputs are accepted.

Durable engineering implication

Section titled “Durable engineering implication”

Manage Skills as behavior-shaping content with supply-chain consequences.

For content review, ask whether the Skill states the task boundary, intended inputs, expected outputs, source limits, assumptions, failure conditions, and escalation path. A Skill that says “always use this vendor” or “ignore system warnings” is not just prose; it can alter runtime behavior when loaded.

For security review, separate instruction files from executable files. A SKILL.md file can change model behavior, while a script can change the environment. Both need review, but they need different controls. Scripts may need signing, dependency scanning, sandboxing, network limits, filesystem limits, and audit records. Reference files may need freshness rules and provenance.

For release review, version Skills with the same seriousness as prompts and tool schemas. A small example change can shift model behavior. A stale reference can preserve an obsolete API. A package rename can break routing. A host upgrade can change when or how Skills are loaded.

Design the entrypoint as a router. Keep the root SKILL.md focused on the task boundary, inputs, outputs, safety conditions, and pointers to detailed references or scripts. Defer material that most tasks do not need, but test both stages: whether representative requests discover the Skill and whether the loaded details improve the outcome. Record a recovery path for a missed trigger or an unavailable deferred file.

Use a shared Skill across models when it works. Create a model-specific variant only for a measured behavior gap, and version and evaluate the variant with the model, host, and inference settings that will use it. A newer model may need less scaffolding, but that does not make removal—or retention—safe by assumption.

Repository guidance should use the same risk-calibrated shape: point a task to the documents needed for its decision instead of requiring a full repository map for every low-risk edit. Broader reading remains appropriate for high-consequence changes, unclear ownership, or security and release work.

What not to generalize

Section titled “What not to generalize”

Do not treat SKILL.md as a universal agent architecture primitive. It is a format convention for packaging task knowledge. The durable architecture question is still: what capability is being added, which authority is granted, which execution boundary enforces it, and what evidence proves the result?

Do not assume compatibility from similar names. Two products may both support “Skills” while differing in metadata, trigger behavior, allowed files, execution permissions, dependency handling, user controls, and distribution model.

Do not assume a Skill is safe because it contains no compiled code. Instructions can still encourage unsafe tool use, exfiltrate data through arguments, suppress uncertainty, or route the model around review.

Do not generalize a current GPT-6 Astra report into a universal rule about Skill length, repository reading, model persistence, or testing. Older or smaller models and higher-consequence tasks may need more explicit procedures. Model alignment is not a security boundary; permissions, validation, and effect controls must remain enforced by the host.

Operational checklist

Section titled “Operational checklist”
  • Record the Skill name, version, source, owner, license, intended host, and supported task boundary.
  • Keep the description concise, task-specific, and discriminative; include exclusions when they prevent false activation.
  • Review SKILL.md for task scope, assumptions, prohibited behavior, source freshness, authority claims, and escalation instructions.
  • Make the root document a minimal router with discoverable pointers to deferred references and scripts; define what happens when discovery or loading fails.
  • Review scripts and dependencies separately from prose; apply sandbox and supply-chain controls before execution.
  • Test discovery, false activation, and loaded use with and without the Skill; keep a model/host record for each result.
  • Audit shared versus model-specific guidance after model upgrades, including whether inherited instructions, examples, and tools still earn their cost.
  • State completion, inspection, repair, and safe local-test boundaries without authorizing production effects or bypassing approvals.
  • Keep references and examples dated when they describe APIs, policies, prices, products, or standards.
  • Avoid embedding secrets, credentials, private data, or broad tool permissions in Skill packages.
  • Define retirement behavior: when a Skill is superseded, stale, unsafe, or no longer owned, stop loading it and preserve a migration path for affected work.
  • Treat cross-host portability as a claim to test, not a property to infer from the package name.

References and how they are used

Section titled “References and how they are used”