Agent Skills: A Cross-Tool Task Knowledge Standard¶

The Agent Skills open standard packages task-specific knowledge into portable SKILL.md folders that AI coding tools can discover and load on demand.

Related lesson: Skills and Progressive Disclosure — this concept features in a hands-on lesson with quizzes.

What the standard defines¶

The Agent Skills standard defines a format for sharing task knowledge across AI coding tools. A skill is a directory with a SKILL.md entrypoint that holds YAML frontmatter and markdown instructions. It can also include supporting files: scripts, templates, examples, or schemas.

The standard is tool-agnostic. Claude Code and GitHub Copilot (VS Code, CLI, and cloud agent) both implement it (VS Code Agent Skills docs, Claude Code skills docs). Other tools, including Cursor and Gemini CLI, have adopted it per the agentskills.io registry. Cross-tool portability is confirmed only for tools that have published implementation documentation.

Skill structure¶

skills/
  writing-rules/
    SKILL.md          # entrypoint with frontmatter + instructions
    templates/        # supporting files
    examples/

SKILL.md frontmatter specifies metadata the tool uses to match skills to tasks:

---
name: writing-rules
description: Style, tone, and structure standards for content pages
version: 1.0.0
---

The markdown body holds the instructions the agent reads.

Discovery and loading¶

Tools discover skills from three locations, in order of precedence:

Project skills — .claude/skills/ or .github/skills/ — committed to the repo, shared with all contributors
User skills — ~/.claude/skills/ — local to the developer, available across all projects
Plugin skills — distributed as part of an installable plugin bundle

Agents load skills on demand. When a task matches a skill's scope, the agent reads SKILL.md and any referenced supporting files. This applies the progressive disclosure pattern to knowledge distribution — see Progressive Disclosure for Agent Definitions.

Portability value¶

Without a standard, skill knowledge is embedded in tool-specific formats. A checklist written for Claude Code's agent format doesn't transfer to GitHub Copilot without manual adaptation. With the standard, the same SKILL.md works wherever the standard is implemented.

This matters for teams using multiple tools and for open-source skill distribution. The github/awesome-copilot repository shows community-scale skill sharing.

Relationship to agent definitions and commands¶

Skills carry domain knowledge. Agent definitions carry identity and skill references. Commands carry orchestration logic. The three layers are distinct:

A writing-rules skill knows what good content looks like
A content-writer agent knows it should use writing-rules for drafting tasks
A draft-content command knows to invoke content-writer after research is complete

Skills are the reusable knowledge layer; agents and commands are not.

In practice¶

A documentation project might maintain skills covering content pipeline management, writing standards, accuracy frameworks, and site navigation. Each agent definition references the skills it needs; each skill is self-contained. A typical project keeps 5 to 15 skills, each focused on one domain concern.

Claude Code implementation: code.claude.com/docs/en/skills.

Example¶

A documentation team maintains a writing-rules skill in .github/skills/writing-rules/:

.github/skills/
  writing-rules/
    SKILL.md
    templates/
      page-template.md

SKILL.md content:

---
name: writing-rules
description: Style, tone, and structure standards for documentation pages
version: 1.2.0
---

# Writing Rules

## Audience
Write for practitioners who deploy and configure agents. Skip introductory definitions; assume working knowledge.

## Structure
Every page opens with a `>` blockquote that defines the concept, not describes the page.

## Tone
Active voice. Present tense. No hedging or meta-framing phrases.

When a contributor runs /draft-content, the agent definition for content-writer references writing-rules. The tool discovers .github/skills/writing-rules/SKILL.md and loads it into context. The agent then applies the style rules, and the contributor does not need to specify them. The same skill file works unchanged in Claude Code, GitHub Copilot, and Cursor.

Why the standard works¶

Portability comes from two design decisions. First, the SKILL.md entrypoint sits at a fixed path that any tool can find without configuration. Tools scan .claude/skills/, .github/skills/, and user-level equivalents because the standard specifies those paths. Second, YAML frontmatter makes skill metadata machine-readable. A tool can match a skill to a task by comparing the description field against the current context, without loading the full instruction body. The progressive disclosure effect follows: only the metadata pays the context cost until the skill activates. (Source: Claude Code skills docs)

When this backfires¶

The standard adds value only when skills need to cross tool or team boundaries. Four conditions make it the wrong choice:

Single-tool, single-developer projects — if one person uses one tool, the portability guarantee is unused overhead. A plain markdown file in CLAUDE.md or a tool-specific command has less structure with no loss.
Rapidly changing instructions — skill files are versioned assets. When guidance evolves daily, the overhead of maintaining SKILL.md directories slows iteration relative to ad-hoc prompting.
Tool mismatch on frontmatter extensions — tools extend the standard with non-portable frontmatter fields (Claude Code adds disable-model-invocation, context: fork; VS Code adds its own fields). Skills that rely on these extensions lose portability quietly — the file loads, but the tool-specific behavior is ignored.
Untrusted skill sources — the same portability that enables cross-tool reuse also lets prompt-injection payloads run wherever the standard is implemented. Snyk's ToxicSkills audit of 3,984 published skills found 534 (13.4%) contained critical-severity issues — 76 confirmed malicious payloads including credential theft and data exfiltration, with 91% of malicious skills combining native code patterns and prompt injection. Treat skills from community registries like any other third-party code dependency: review them, pin them, and sandbox them, rather than trusting them by default because they loaded cleanly.

Key Takeaways¶

Skills are directories with a SKILL.md entrypoint: frontmatter metadata + markdown instructions
The Agent Skills standard enables the same skill to work across multiple AI coding tools; confirmed implementors include Claude Code and GitHub Copilot
Discovery order: project → user → plugin
Skills carry domain knowledge; agent definitions reference them; commands orchestrate agents
Community distribution: skills as git repos, installable by URL or plugin bundle