Agent Skills Guide

TL;DR

• A skill packages a repeatable procedure. It normally contains a SKILL.md manifest plus instructions, scripts, examples, or templates.
• Skills are not tools. A skill tells an agent how to work; a tool or MCP server performs an action or exposes a capability.
• Selective loading matters. Keep a skill focused so irrelevant instructions do not consume context or conflict with the current task.
• Treat every skill as untrusted input until reviewed. Instructions can influence tool use, data handling, and escalation decisions.
• Version and test skills. A good skill has scoped triggers, fixtures, expected outputs, and an owner—just like a runbook or library.

Why This Matters

Teams quickly accumulate prompts for release notes, incident triage, migrations, and code review. Copying those procedures into every conversation makes them drift; putting all of them in a global system prompt makes every task noisier and less predictable. Agent Skills provide a middle ground: a named package is discovered from lightweight metadata and loaded only when it fits the task.

That packaging is now supported across multiple agent surfaces. OpenAI documents Skills for shell and sandboxed agent sessions, while GitHub Copilot supports repository and personal skills across its app, CLI, cloud agent, code review, and IDE agent modes. The useful abstraction is the portable procedure—not a particular vendor’s picker.

The Problem Agent Skills Solve

Without skills, reusable agent procedures commonly fail in four ways:

1. Prompt drift: each developer copies a slightly different release process.
2. Context bloat: all instructions are loaded for every task, including unrelated ones.
3. Unreviewed automation: a prompt quietly grows shell commands, credentials, or deployment steps.
4. No ownership: nobody knows which procedure is current or how to safely change it.

Skills make the procedure a reviewable artifact. They do not solve authorization, orchestration, or tool integration; those remain runtime concerns.

How We Got Here

Diagram: From prompts to reusable agent procedures

flowchart LR
    A[Ad hoc prompt] --> B[Prompt template]
    B --> C[Global instructions]
    C --> D[Task-specific skill]
    D --> E[Versioned skill library]

Skills add selective discovery and supporting resources to the familiar prompt-template pattern.

What Is an Agent Skill?

An Agent Skill is a directory with a manifest—commonly SKILL.md—and optional supporting files. The manifest gives the runtime enough metadata to decide whether to load it; the body tells the agent how to carry out a task. Supporting files can hold a template, a validation script, examples, or a domain glossary.

.agents/skills/
  release-notes/
    SKILL.md
    template.md
    scripts/collect-changes.sh

Skills versus nearby concepts

What is new is not instruction-following or tool calling. It is a portable package boundary that lets an agent discover a focused procedure and its resources on demand.

How Agent Skills Work

Diagram: Skill discovery and execution

sequenceDiagram
    participant U as User
    participant R as Agent runtime
    participant S as Skill library
    participant T as Tools
    U->>R: Prepare release notes
    R->>S: Match task to skill metadata
    S-->>R: Load SKILL.md and resources
    R->>T: Use already-authorized tools
    T-->>R: Results
    R-->>U: Draft plus validation notes

The skill can shape the procedure, but the runtime still owns tool permission and execution.

Architecture

Diagram: Production skill boundary

flowchart TB
    A[Repository skill library] --> B[Discovery metadata]
    B --> C[Selected SKILL.md]
    C --> D[Agent context]
    D --> E[Authorized tools and MCP]
    D --> F[Validation scripts]
    E --> G[Audited output]
    F --> G

Write a skill contract before the instructions

Before writing a long procedure, record a compact contract. It prevents a useful skill from quietly becoming an autonomous operator as contributors add requests over time.

A contract is not a permission system. The runtime must separately enforce filesystem, network, credential, and deployment access. Its value is that reviewers can compare the prose, scripts, and tests against an explicit intended boundary. If a new requirement would change an allowed write from “none” to “open a pull request,” treat it as a material change: update the contract, request review, and test the new behavior.

Resource design: instructions are not the whole skill

Keep reusable artifacts beside the manifest, but avoid hiding operational logic in prose. A template is appropriate for a release-note heading hierarchy; a script is appropriate for collecting merged pull requests; a JSON schema is appropriate for a machine-consumed result. The agent should explain and compose those resources, not reimplement a deterministic parser from a paragraph of instructions.

This separation also improves incident response. If a generated draft has the wrong format, inspect the template and the selection trace. If it omitted a merged change, inspect the collector’s fixture and its range calculation. If it tried an unauthorized action, inspect the runtime’s tool policy—not just the skill text. Each layer then has one job and a testable failure mode.

As the library grows, publish a short catalog with owner, scope, risk level, and last-reviewed date for every skill. Discovery improves when names describe outcomes rather than internal team jargon, and retirement becomes safer when callers can see the designated replacement.

Review that catalog during normal engineering maintenance cycles.

Step-by-Step Flow

1. Define the bounded outcome. For example, “draft release notes from merged pull requests,” not “handle releases.”
2. Write a short trigger description. Include when to use the skill and when not to use it.
3. Put durable instructions in SKILL.md. Link to supporting templates rather than duplicating them.
4. Separate judgment from deterministic checks. Put linting and data collection in scripts; ask the model to interpret results.
5. Use only runtime-authorized tools. A skill must not imply permission to deploy, read secrets, or call an external system.
6. Add fixtures and acceptance criteria. Test a representative request before publishing a new version.

Real Production Example

---
name: release-notes
description: Draft customer-facing release notes from merged changes. Use only for a named release window; do not publish or modify changelogs.
---

1. Run `scripts/collect-changes.sh <from> <to>`.
2. Group accepted changes under Added, Changed, Fixed, and Deprecated.
3. Exclude internal refactors and security-sensitive detail.
4. Cite each pull request number in an internal review appendix.
5. Return a draft; do not publish it.

The accompanying script can retrieve a deterministic list of changes. The agent adds editorial judgment, but the skill leaves publication to a separately authorized workflow.

Design Decisions

Common Mistakes

1. Putting credentials in a skill. Store secrets in the runtime’s approved secret mechanism; skills should never contain them.
2. Using a skill as an access-control system. “Do not deploy” in prose is not a permission boundary.
3. Making one giant “engineering” skill. It creates context noise and contradictory instructions.
4. Embedding mutable facts in instructions. Link to a maintained source or fetch the fact through an approved tool.
5. Skipping negative triggers. State when a skill must not apply, especially around production changes and sensitive data.

Comparisons

Agent Skills vs custom instructions

Custom instructions establish the baseline rules for a repository or organization: language versions, code style, review expectations, and prohibited actions. They should be short because they accompany broad classes of work. A skill is a narrower procedure that may add a release template, a migration checklist, or domain-specific validation only when needed.

Agent Skills vs MCP

MCP answers a different question: how can an agent host discover and invoke an external capability? A skill may tell an agent which MCP tools to prefer, how to sequence their calls, and which output to validate. It cannot create the connection, authenticate to the service, or override an MCP server’s authorization policy.

Agent Skills vs custom agents and hooks

Use a custom agent when the work needs a separate execution identity, model choice, context boundary, or a formal handoff. Use a hook or CI job when an action must always occur at a lifecycle point. A skill fits between them: it improves a model’s task execution without making that behavior mandatory or granting extra authority.

Decision tree: choose the smallest mechanism

flowchart TD
    A[Need repeatable behavior?] -->|No| B[Use a prompt]
    A -->|Yes| C{Must run every time?}
    C -->|Yes| D[Use a hook or CI]
    C -->|No| E{Need a separate role or context?}
    E -->|Yes| F[Use a custom agent with skills]
    E -->|No| G[Use a focused skill]

Start with the smallest construct that provides the required reliability and boundary.

Testing a skill before rollout

Test both selection and behavior. Selection tests use task descriptions that should and should not match the skill. Behavior tests use fixed fixtures and assert on the final artifact, the tools requested, and any refusal or escalation. For a database-migration skill, include a prompt that asks it to run against production; the expected outcome should be a clear escalation, not a command.

Maintain a small regression set whenever the skill changes. If the runtime exposes traces, compare selected skill names, resources read, tool calls, and output sections across versions. For high-risk skills, ship a disabled or canary version first and require a human reviewer to inspect the first runs.

Selection is a product decision

Skill discovery is often probabilistic: the runtime compares a user task with a skill name and description, then decides whether reading the full package is worthwhile. Design the description as an interface, not marketing copy. Name the concrete outcome, the expected inputs, and important exclusions. “Handle releases” is vague; “draft release notes from merged pull requests for a named range; do not publish” gives the agent a usable boundary.

Overlapping skills create a subtle failure mode. If release-notes, changelog, and customer-summary all claim to summarize changes, the agent may load the wrong package or multiple conflicting ones. Prefer one canonical skill with variants in its inputs, or distinguish them with clearly different artifacts and audiences. Keep a test prompt for each intended match and near-match. A selection failure is still a production failure even when the selected skill executes correctly.

Selection also affects cost and privacy. Loading a skill can expose internal templates and consume context before the model has done useful work. Do not use skill metadata to smuggle sensitive instructions into broad contexts. Store confidential data behind a purpose-built, authorized resource or tool, and make the skill explain how to request it safely. Where a runtime permits user-installed skills, provide an allowlist and provenance review process instead of assuming every local directory is trustworthy.

Finally, record the selected skill in user-visible or operational output when it changes the result materially. A reviewer should be able to answer: which procedure was used, which version was loaded, which resources affected the answer, and whether a fallback was taken. That trace turns a library of prompts into an operable engineering system.

Skill review checklist

Before accepting a change, review it with the same questions used for a small automation change. Does the title state a bounded outcome? Does the description say when to use it and when not to? Are input assumptions explicit? Can a contributor follow every reference without private tribal knowledge? Are examples representative but free of credentials, customer data, and production identifiers?

Then inspect authority. List every tool, external service, filesystem path, and network destination the skill asks an agent to use. Verify that each is available through an approved runtime integration and that the least-privilege policy still applies. A skill that suggests “use curl with the deployment token” should be rejected even if the token is not in the file: it embeds an unsafe operational pattern. Prefer a dedicated deploy tool with an approval gate and a dry-run mode.

Finally, review maintenance. Add an owner, a last-reviewed date, test fixtures, and a deprecation path. Link to the source of mutable product or policy facts rather than copying them into the instructions. When a change alters tool use, data exposure, or publishing behavior, request security or platform review. These modest controls keep a skill library useful as it grows instead of turning it into an untracked second policy system.

Document review outcomes in the pull request so later maintainers understand the intended safety boundary and any accepted tradeoffs.

Where It Breaks Down

Skills do not make an ambiguous task deterministic. They also cannot guarantee a model will follow every instruction, secure an unsafe tool, or replace a workflow engine for retries and approvals. Use durable execution for long-running state, guardrails for policy checks, and CI or hooks for mandatory deterministic enforcement.

When NOT to Use Agent Skills

Skip a skill when:

1. The instruction applies everywhere. Use repository-level custom instructions.
2. The operation must be deterministic. Use a script, CI check, or hook.
3. The task needs a live integration. Add an approved tool or MCP server first.
4. The task is a one-off prompt. A short prompt file is simpler and easier to review.

Running in Production

Best Practice

✅ Best Practices — Review skills like code, limit each skill’s authority by runtime policy, and test with adversarial as well as happy-path prompts.

Related Guides

• AI Agents: The runtime loop that may discover and use a skill.
• Workflows vs Agents: When a procedure should be deterministic instead.
• Model Context Protocol: The separate protocol layer for capabilities and tools.
• Tool Calling: How models propose an action after a skill guides the task.
• Guardrails: Controls that constrain what an agent may do.

Diagram: Learning path for Agent Skills

flowchart LR
    A[AI agents] --> B[Agent skills]
    B --> C[Tool calling]
    B --> D[Guardrails]
    C --> E[MCP]

Interview Questions

1. What is the difference between an agent skill and an MCP server?
   • Expected: a skill is guidance and resources; MCP exposes capabilities.
2. Why should a skill not grant deployment authority?
   • Expected: instructions are not an enforcement boundary; runtime permissions must control actions.
3. How would you test a release-notes skill?
   • Expected: fixtures, expected sections, negative cases, and checks that it never publishes.
4. When should an instruction be global rather than a skill?
   • Expected: when it applies to nearly every task in the repository.
5. What should an audit record include?
   • Expected: selected skill version, resources, tool calls, outputs, and validation results.

Key Takeaways

• Skills are reusable, scoped procedures—not tools, agents, or policy engines.
• Keep the manifest narrow and attach templates or scripts as separate resources.
• Runtime permissions, validation, and audit logs remain essential in production.

FAQs

Are Agent Skills the same as prompts?

They contain instructions, but also provide a discoverable package boundary and supporting files. A one-off prompt does not need that machinery.

Can a skill call an MCP server?

A skill can instruct an agent to use one, but only if the runtime has already exposed and authorized that server.

Should every repository have skills?

No. Add them for procedures that recur, have meaningful context, and benefit from reviewable supporting resources.

Can skills be shared across products?

Some runtimes support the open Agent Skills format, but supported locations, selection behavior, and permissions differ. Validate portability before relying on it.

How small should a skill be?

Small enough that one owner can test its outcome and one description can clearly state when it applies.

Are skills safe by default?

No. They are instructions and may bundle scripts. Review their contents and run them with least-privilege tools.

Do skills replace custom agents?

No. Use a custom agent when the role, model, context, or handoff needs its own execution boundary; attach skills to teach it reusable procedures.

How do I retire a skill?

Disable discovery, preserve a migration note, update callers, and remove it only after consumers no longer depend on it.

References

• OpenAI Skills documentation
• GitHub Copilot Agent Skills documentation
• GitHub Copilot customization cheat sheet