Published February 21, 2026 by with 0 comment

Agent Skill



1. Concept
A skill is a set of instructions - packaged as a simple folder - that teaches AI module how to handle specific tasks or workflows
In other word, skill just a documentation.


2. Fundamentals
your-skill-name/
├── SKILL.md # Required - main skill file
├── scripts/ # Optional - executable code
│ ├── process_data.py # Example
  ├── upload.py # Example
│ └── validate.sh # Example
├── references/ # Optional - documentation
│ ├── api-guide.md # Example
  ├── finance.md # Example
│ └── examples/ # Example
└── assets/ # Optional - templates, etc.
  └── report-template.md # Example
 
A skill is a folder containing:
• SKILL.md (required): Instructions in Markdown with YAML frontmatter
• scripts/ (optional): Executable code (Python, Bash, etc.)
• references/ (optional): Documentation loaded as needed
• assets/ (optional): Templates, fonts, icons used in output

Skill folder naming:
• Use kebab-case: notion-project-setup ✅
• No spaces: Notion Project Setup ❌
• No underscores: notion_project_setup ❌
• No capitals: NotionProjectSetup ❌

SKILL.md naming:
• Must be exactly SKILL.md (case-sensitive)

No README.md:
• Don't include README.md inside your skill folder


3. Three types of Skill content
3.1. Metadata (always loaded)
Minimal required format:
---
name: your-skill-name
description: What it does. Use when user asks to [specific phrases].
---

name (required):
• kebab-case only (e.g. meeting-summary)
• No spaces or capitals
• Should match folder name

description (required):
• MUST include BOTH:
– What the skill does
– When to use it (trigger conditions)
• Include specific tasks users might say
• Mention file types if relevant

Examples of good descriptions:

# Good - specific and actionable
---
description: Analyzes Figma design files and generates developer handoff documentation.
Use when user uploads .fig files, asks for "design specs", "component documentation", or "design-to-code handoff".
---

# Good - includes trigger phrases
---
description: Manages Linear project workflows including sprint planning, task creation, and status tracking.
Use when user mentions "sprint", "Linear tasks", "project planning", or asks to "create tickets".
---

# Good - clear value proposition
---
description: End-to-end customer onboarding workflow for PayFlow. 
Handles account creation, payment setup, and subscription management.
Use when user says "onboard new customer", "set up subscription", or "create PayFlow account".
---


3.2. Instructions (loaded when triggered)
The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance.
Instructions should be specific and actionable.

---
# Instructions
### Step 1: [First Major Step]
Clear explanation of what happens.
Example:
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
Expected output: [describe what success looks like]
---

Examples of good instructions:
---
# Instructions
Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# Common Issues
### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Your Service] > Reconnect
---

This diagram shows how the user, the agent, and the AI model interact and communicate via skills.




3.3. Resources and code (loaded as needed)
3.3.1. Reference
Additional markdown files (api-patterns.md, finance.md) containing specialized guidance and workflows

When the AI model analyzes the user's input and determines that a specific SKILL.md needs to be provided by an agent, it requests the corresponding agent to supply it.
Based on the “reference” section within SKILL.md, the model may further determine that an additional referenced Markdown file is required.
The agent, following the AI model’s instruction, then sends the specific referenced .md file back to the AI model.

It is call "loaded when triggered".

---
# Reference
Before writing queries, consult `references/api-patterns.md`
for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling
---

---
# Reference
When keywords related to finance (e.g., "money", "fee", "claim") are detected, reference `references/finance.md`.
---


3.3.2 Code
Executable scripts (fill_form.py, validate.py) that agent runs via bash; scripts provide deterministic operations without consuming context

The AI model determines that a specific tool is required, such as keywords "upload" or "sync to xxx".
The AI issues a tool call or execution request.
The agent executes `scripts/upload.py` at the system level.
The script runs outside the model environment.
The agent only executes the script; it does not read the script content.
No AI context tokens are consumed during script execution.

For example:
---
# Script
When keywords such as "upload" or "sync to xxx" are detected, execute `scripts/upload.py`.
---

Reference are read by the AI model, so they consume tokens.
Scripts are executed by the agent, so they do not consume AI tokens.


Skills use a three-level system:
4.1. First level (YAML frontmatter): Metadata (Always loaded).
Provides just enough information for AI to know when each skill should be used without loading all of it into context.

4.2. Second level (SKILL.md body): Instructions (Loaded when triggered)
Loaded when AI thinks the skill is relevant to the current task. Contains the full instructions and guidance.

4.3 Third level (Linked files): Resources and code (Loaded as needed)
Additional files bundled within the skill directory that AI can choose to navigate and discover only as needed.

This progressive disclosure minimizes token usage while maintaining


5. For MCP
MCP:
Connects AI to your service (Notion, Asana, Linear, etc.)
Provides real-time data access and tool invocation
What AI can do

Skill:
Teaches AI how to use your service effectively
Captures workflows and best practices
How AI should do it

MCP provides the professional kitchen: access to tools, ingredients, and equipment. Essence: Code
Skills provide the recipes: step-by-step instructions on how to create something valuable. Essence: Documentation


Reference:

2.Agent Skills - Claude API Docs

3. anthropics/skills: Public repository for Agent Skills


First Published (YYYY-MM-DD) / Last Modified (YYYY-MM-DD)
2026-02-21 / 2026-02-21

0 comments:

Post a Comment

Subscribe to: Post Comments (Atom)