Claude Agent Skills Explained: Differences, Installation, and Practical Use

Agent Skills Overview

Agent Skills are directories that contain a SKILL.md metadata file, optional scripts, and resource files (PDF, DOCX, etc.). The metadata includes name, description, and a list of actions. When a user request matches a skill, the agent loads only the metadata; the heavy body files are fetched on demand, implementing progressive disclosure.

Comparison: Skills, Rules, MCP

Skills – static packages of expert knowledge and step‑by‑step procedures. Only metadata stays in context; body and auxiliary files are loaded when the skill is invoked.

Rules – global prompts, behavior constraints, or tool‑usage policies. Typically loaded in full or trimmed to a minimal set; cannot be partially loaded.

Model Context Protocol (MCP) – a toolbox layer that wraps APIs, knowledge bases, or workflows, giving the agent tool‑calling capabilities.

Skills solve the “model knows a little about everything but lacks deep process knowledge” problem, while Rules define the overall contract and MCP provides the mechanism to call external tools.

Installation in Claude Code

Official skill repository: https://github.com/anthropics/skills

Add the official marketplace: /plugin marketplace add anthropics/skills Third‑party marketplace example: /plugin marketplace add chujianyun/skills Installed plugins reside under ~/.claude/plugins. They can be enabled, updated, or removed at user, project, or local scope. After installation, restart the terminal for the plugins to take effect.

Prompt‑Optimizer Skill Walk‑through

User submits a prompt that needs optimization.

Agent matches the prompt-optimizer skill and loads its SKILL.md.

Agent reads Frameworks_Summary.md to obtain a list of available prompt‑engineering frameworks (e.g., RACE, TRACE).

Based on the user’s scenario, the agent selects the most suitable framework (e.g., RACE) and loads the corresponding detailed description files such as 15_RACE_Framework.md or 44_TRACE_Framework.md.

If the selected framework description contains ambiguities, the agent asks the user for clarification.

Finally the agent generates a clearer, professional prompt using the selected framework.

This flow demonstrates progressive disclosure: only the skill’s metadata is always present; heavy framework files are fetched only when needed, avoiding token bloat.

Context Overhead Comparison

Rules are monolithic; loading a rule brings all its content into the model context, which can waste tokens when many frameworks are present. Skills keep only lightweight metadata in context and load detailed bodies on demand, allowing hundreds of frameworks to coexist without inflating the token count.

Technical Details of Skill Definition

A typical SKILL.md structure:

name: "prompt-optimizer"
description: "Optimizes user prompts by selecting a suitable framework"
actions:
  - read: "Frameworks_Summary.md"
  - select: "RACE"
  - load: "15_RACE_Framework.md"
  - confirm: true

Auxiliary files referenced in SKILL.md (e.g., forms.md) are loaded only when the skill explicitly references them.

Example Marketplace JSON Snippet

{
  "name": "anthropic-agent-skills",
  "owner": {"name": "Keith Lazuka", "email": "[email protected]"},
  "metadata": {"description": "Anthropic example skills", "version": "1.0.0"},
  "plugins": [
    {
      "name": "document-skills",
      "description": "Document processing suite (Excel, Word, PDF, etc.)",
      "source": "./",
      "strict": false,
      "skills": ["./skills/pdf", "./skills/docx"]
    },
    {
      "name": "example-skills",
      "description": "Demonstrates skill creation, MCP building, visual design, etc.",
      "source": "./",
      "strict": false,
      "skills": ["./skills/prompt-optimizer"]
    }
  ]
}

The marketplace JSON is stored at ~/.claude/plugins/.claude-plugin/marketplace.json and can be edited to add or remove skill collections.

Key Takeaways

Progressive disclosure reduces token consumption and improves model efficiency.

Skills provide modular, reusable procedural knowledge that can be invoked on demand.

Choosing a more capable underlying model (e.g., Claude 3) can further improve the results of a given skill.