Claude Agent Skills Landing Guide: Structure, Decision Matrix & SKILL.md Templates

Table of Contents

1. Executive Summary
2. Why Skills: Core Problems and Paradigm Shift
3. What is a Skill: Structure, Boundaries & Progressive Disclosure
4. Skill Lifecycle: Discovery→Activation→Execution
5. System Architecture Perspective: Where Skills Fit in the Agent Stack
6. Coordination and Trade-offs with Prompt / Projects / Subagents / MCP
7. Comparison Table & Decision Matrix: When to Use What
8. Comprehensive Case Study: Modular Assembly of a Competitive Intelligence Agent
9. Skill Authoring & Engineering Best Practices
10. Security, Governance & Controlled Autonomy
11. Appendix: SKILL.md Templates & Multi-file Structure Examples
12. References

Executive Summary

Agent Skills is a “composable, portable, on-demand” procedural knowledge encapsulation mechanism introduced by Anthropic in 2025: it uses directories in the file system to package instructions + optional resources (documents, scripts, templates) into capability modules that Claude automatically invokes based on description matching during conversations. The core value isn’t “reinventing Prompt,” but rather engineering the solidification of repeatedly occurring procedural knowledge, while controlling context costs within predictable bounds through progressive disclosure.

From an architectural standpoint, Skills are the “method layer” in the Agent capability stack. They don’t replace:

• Projects (background knowledge and long-term context)
• MCP (channel layer for connecting external systems/data)
• Subagents (execution units for task division and context isolation)

They’re more like turning “organizational SOPs, review checklists, writing standards, operational procedures, and scripted toolchains” into reusable “training manuals + toolboxes,” thereby significantly improving consistency, auditability, and scalable reuse capabilities.

Why Skills: Core Problems and Paradigm Shift

The core shortcoming of large models isn’t “inability to answer,” but rather:

1. Poor cross-session consistency: The same team SOP gets prompted repeatedly with slight variations each time, causing results to drift.
2. Procedural knowledge is hard to preserve faithfully with ad-hoc prompts: Multi-step workflows, compliance checks, and format requirements are essentially “process constraints,” not “language explanations.”
3. Context is a scarce resource: Stuffing the complete methodology into every conversation causes context squeeze and attention competition.

The innovation of Skills can be summarized in one sentence:

Turn the content of “teaching a new employee how to do things” into a set of manuals that can be browsed on-demand; AI first looks at the table of contents (name/description), then opens specific chapters when needed (SKILL.md), and loads appendix files on-demand for details.

This brings an important paradigm shift: from Prompt-driven (telling it the method each time) to Procedure-driven (having it follow the method long-term).

What is a Skill: Structure, Boundaries & Progressive Disclosure

Three Types of Skill “Assets”

A Skill directory typically contains:

• SKILL.md: The only required entry file, containing YAML frontmatter (name/description, etc.) + Markdown instruction body.
• Reference materials (optional): Multiple .md or resource files, loaded on-demand (not in context by default).
• Scripts/tools (optional): Executable scripts for deterministic processing, turning “reasoning” into “execution.”

Why Progressive Disclosure is the Key Design

Progressive disclosure solves an engineering problem: the contradiction between capability expansion and context cost.

• The entry file (SKILL.md) must be short enough to avoid crowding reasoning space every time it’s activated; official guidance recommends keeping SKILL.md body to under 500 lines, splitting into separate files when necessary.
• “Detail files” don’t consume tokens until accessed, allowing you to put a large amount of organizational standards/manuals in without causing bloat at startup.

Skill “Boundaries” and Misuse Warnings

Skills are not suitable for:

• “Long-term factual memory” (that’s Projects / RAG’s responsibility).
• “External system connectivity” (that’s MCP’s responsibility).
• “Complex parallel execution and context isolation” (that’s Subagents’ responsibility).

Skills are best suited for: stable, repeatable, auditable ways of doing things.

Skill Lifecycle: Discovery→Activation→Execution

Flowchart (Mermaid)

    flowchart TD
  U[User Request] --> M{Matches Skill Description?}
  M -- No --> P[Execute via Default Conversation/Prompt]
  M -- Yes --> D[Discovery: Load only name/description]
  D --> A[Activation: Request to use Skill, load SKILL.md]
  A --> E[Execution: Complete task per instructions]
  E --> L{Need more details?}
  L -- Yes --> R[Load referenced files/run scripts on-demand]
  L -- No --> O[Output Result]
  

Note: Claude loads only each Skill’s name/description at startup for quick matching; SKILL.md is loaded only after a match, and referenced materials are loaded on-demand during execution.

Key mechanism points:

• Discovery: Read only metadata, stay lightweight.
• Activation: Request enablement and load SKILL.md after matching description.
• Execution: Follow instructions; read files or run scripts if details are needed.

System Architecture Perspective: Where Skills Fit in the Agent Stack

Architecture Diagram: From “Connectivity” to “Division of Labor” to “Methods”

    graph TB
  subgraph Surface[User Interaction Layer]
    UI[Conversation/Request]
  end

  subgraph Orchestration[Orchestration & Planning Layer]
    Planner[Task Decomposition & Planning]
    Policy[Permission/Governance Policies]
  end

  subgraph Capability[Capability Layer]
    Skills[Skills: Procedural Knowledge + Resources/Scripts]
    Prompt[Prompt: Ad-hoc Instructions]
    Project[Projects: Persistent Context/Knowledge Base]
  end

  subgraph Execution[Execution Layer]
    Subagents[Subagents: Division of Labor + Isolated Context]
    Tools[Tools/VM/File System/Runtime Environment]
  end

  subgraph Connectivity[Connectivity Layer]
    MCP[MCP: External Systems & Data Channels]
  end

  UI --> Planner --> Skills
  UI --> Planner --> Prompt
  UI --> Planner --> Project
  Planner --> Subagents --> Tools
  Skills --> Tools
  Tools <--> MCP
  Planner --> Policy
  Policy --> Tools
  

• Skills handle “how to do it” (procedural knowledge), Projects handle “what is known,” MCP handles “how to get the data,” and Subagents handle “who does it and how to isolate.”

Directory Priority & Deployment Scope

A Skill’s storage location determines its visibility scope; if same-named Skills conflict, priority order is: Enterprise (managed/organization) > Personal > Project > Plugin.

• Personal: ~/.claude/skills/ (available across personal projects)
• Project: .claude/skills/ (shared at repository level)

Coordination and Trade-offs with Prompt / Projects / Subagents / MCP

This section doesn’t repeat concepts—it focuses on essential differences: they solve different system bottlenecks.

Prompt: On-the-spot command (high flexibility, low reuse)

• Suitable for: One-time tasks, interactive fine-tuning, immediate context supplementation.
• Not suitable for: Processes and standards requiring long-term consistency.

Projects: Long-term background (memory and knowledge base)

• Suitable for: Long-term work around the same topic/project, accumulating materials and context.
• Not suitable for: Cross-project universal methodologies (that’s more like Skills).

Subagents: Division of labor and isolation (multi-threaded execution units)

• Suitable for: Decomposable tasks, parallel exploration, permission isolation (e.g., read-only audit vs. writable modification).
• Not suitable for: Hard-coding “process specifications” into each sub-agent; should be abstracted into Skills for all agents to reuse.

MCP: External system “tentacles” (connectivity layer)

• Suitable for: Continuous connection to data sources and business systems (Drive/Slack/GitHub/DB, etc.).
• Not suitable for: Carrying “how to use data” methods (that’s Skills).

Comparison Table & Decision Matrix: When to Use What

Core Comparison Table (Condensed Version)

The comparison logic aligns with official definitions: Skills=procedural knowledge, Projects=persistent context, Subagents=delegation & isolation, MCP=connectivity.

Decision Matrix (Ready for Team Standards)

allowed-tools is currently only supported in Claude Code’s Skills.

Comprehensive Case Study: Modular Assembly of a Competitive Intelligence Agent

Objective

Build a “Competitive Intelligence Analysis Agent” that takes a one-sentence request and outputs:

• Structured report (executive summary, comparison, insights, recommendations)
• Evidence chain (citing sources/documents/data)
• Reusable process (faster and more stable for similar tasks next time)

Component Assembly Diagram

    graph LR
  U[User Request: Analyze competitor AI features and gaps] --> P[Project: Competitive Intelligence Library<br/>Industry Reports/Historical Summaries]
  U --> MCP[MCP: Drive/Slack/GitHub/DB<br/>Fetch latest materials]
  U --> S[Skill: Competitive Analysis Framework<br/>Search Strategy/Analysis Dimensions/Report Template]
  S --> SA[Subagents: Market Research / Technical Analysis / Evidence Verification]
  P --> SA
  MCP --> SA
  SA --> R[Main Agent Aggregation: Form Report & Recommendations]
  

Explanation: Project provides “what’s known,” MCP provides “what’s new,” Skills provide “methods,” Subagents provide “division of labor and isolation.” This is exactly the composable workflow path emphasized by the official documentation.

Key: Put “Reusable” into Skills

A competitive analysis Skill shouldn’t store “facts about a specific competitor,” but should store:

• Search strategy (recent 6 months first, prioritize authoritative sources, how to determine final version)
• Analysis framework (positioning→capabilities→differences→risks→opportunities→recommendations)
• Evidence requirements (every key conclusion must cite source/provide confidence level)
• Output specifications (report structure, table fields, comparison dimensions)

This way, facts are supplied by Project/MCP, methods are solidified by Skills, truly forming “organizational capability.”

Skill Authoring & Engineering Best Practices

1. Treat Skills as “Software Engineering Assets”

What you’re writing isn’t “prompt words,” but:

• Versionable (Git)
• Auditable (compliance/security)
• Testable (trigger rate, output consistency)
• Maintainable (update as processes evolve)

2. Description is the “Routing Rule”

Claude primarily relies on description to decide whether to trigger a Skill, so description needs to answer both:

• What it does (capabilities)
• When to use it (trigger terms) And should include keywords users would actually say.

3. Entry File Should Be “Short, Hard, Executable”

• Keep SKILL.md body under 500 lines; split complex content into sub-files.
• Express instructions as “action-oriented”: give steps, give checklists, give acceptance criteria.
• Delegate “determinism” to scripts: complex calculations/format validation/batch processing should be scripted whenever possible.

4. Use Fork to Protect Main Conversation Context

For “multi-step, noise-prone” Skills, use context: fork to execute in isolated context.

5. Use Hooks to Front-load “Governance” to Tool Calls

Hooks can be used to perform security checks or inject additional context before/after tool calls; supports PreToolUse / PostToolUse / Stop.

Security, Governance & Controlled Autonomy

The power of the Skill system comes from “executability,” and so do the risks. Governance key points:

1. Principle of least privilege: If read-only works, don’t give write access; if tools can be restricted, restrict them.
2. Prevent Prompt Injection: Write explicit rules about “which inputs to trust, which files are authoritative, how to handle conflicts.”
3. Auditability: Output must include evidence chain; critical operations (delete/overwrite/financial actions) must require secondary confirmation.
4. Supply chain security: Only import Skills/scripts from trusted sources, especially skill packages with hooks.

The engineering blog also emphasizes that security boundaries need to be taken seriously when combining Skills with real-world operations.

Appendix: SKILL.md Templates & Multi-file Structure Examples

A. Minimal Viable Template (Single File)

name: competitive-analysis description: Competitive intelligence analysis framework and report template. Used for structured comparison of competitor features, positioning, and technical roadmaps, outputting actionable recommendations. Trigger terms: competitor, competitive, comparison, differentiation, market positioning, tech stack, opportunity.

Competitive Analysis Skill

Objective

• Produce structured competitive report (with evidence chain)
• Provide source and confidence level for each key conclusion
• Output actionable opportunity and risk lists

Workflow (Must Follow Sequence)

1. Define analysis scope: competitor list, time window, target market
2. Collect evidence: prioritize authoritative materials from recent 6 months; list sources
3. Build comparison table: positioning/features/business model/technical roadmap/ecosystem
4. Output insights: differences, gaps, replicable practices, non-replicable barriers
5. Give recommendations: short/mid/long-term roadmap + validation experiments (with metrics)

Output Format (Fixed)

• Executive Summary
• Evidence List (links/document names/dates)
• Comparison Table (Markdown table)
• Key Insights (3-7 items)
• Recommendations & Next Steps (including experiment design)

B. Multi-file Structure (Progressive Disclosure)

competitive-analysis/ ├── SKILL.md # Entry: workflow + output specs (short) ├── FRAMEWORK.md # Detailed analysis framework & dimension definitions (load on-demand) ├── SOURCES.md # Authoritative source priorities & filtering rules (load on-demand) ├── EXAMPLES.md # Success cases (load on-demand) └── scripts/ ├── dedupe_sources.py # Source deduplication/sorting (execute, don’t load) └── score_confidence.py # Confidence calculation (execute, don’t load)

Progressive disclosure and the 500-line recommendation are core content of official best practices.

References

1. Anthropic Engineering: Equipping agents for the real world with Agent Skills.
2. Claude Blog: Skills explained: How Skills compares to prompts, Projects, MCP, and subagents.
3. Claude Docs: Agent Skills overview.
4. Claude Docs: Skill authoring best practices (including 500-line recommendation, progressive disclosure pattern).
5. Claude Code Docs: Agent Skills (paths, priorities, allowed-tools, context fork, hooks).