Skip to content
Agentic Engineering Fieldbook

Agent Skill Formats and Extensions

Observation date and maintenance

Section titled “Observation date and maintenance”

Observed on 2026-07-23.

Applicable surfaces: Agent Skills specification, OpenAI Tools and Skills documentation, and Claude Skills product documentation.

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.

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.

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.

Operational checklist

Section titled “Operational checklist”
  • Record the Skill name, version, source, owner, license, intended host, and supported task boundary.
  • Review SKILL.md for task scope, assumptions, prohibited behavior, source freshness, authority claims, and escalation instructions.
  • Review scripts and dependencies separately from prose; apply sandbox and supply-chain controls before execution.
  • Test with and without the Skill loaded to see whether it improves the intended outcome or merely changes style.
  • 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”