1.Skill

👉 #AI #LLM #Agent #Prompt #DevTools

I. Agent Skills (AI Skill)

📅 2026-04-27 CDT; Claude Opus 4.6 📎 Agent Skills Open Standard 📎 Claude Skills Official Docs 📎 Kiro Skills Docs 📎 Hermes Agent Skills 📎 Agent Skills SDK (Microsoft) 📎 Claude Code Skills Guide (fp8.co) 📎 Agent Skills 101 (serghei.pl)

1. Overview

1.1. Definition & Why

An Agent Skill is an open-standard format that packages domain knowledge, workflow instructions, scripts, and templates into a reusable bundle that an AI Agent can load and execute on demand.
The core file is SKILL.md — a file with YAML frontmatter (metadata) plus a Markdown body (instructions), optionally accompanied by scripts/, references/, and assets/ subdirectories.
Design intent: solve the "repeated teaching" problem of AI Agents.
Re-explaining team conventions, deployment flow, and code style in every conversation wastes time and tokens.
Different projects, teams, and Agent platforms can't share knowledge — duplicate effort.
Without domain context, Agents can only guess and iterate — quality is unstable.
Essence of a Skill: documentation written for the AI plus an executable resource bundle. Write once; the Agent follows it every time.
Originally developed by Anthropic and released as an open standard; now adopted by 20+ Agent platforms.

1.2. Features & Use Cases

(1) Core Features

Feature	Description
Progressive Disclosure	Agent first reads name + description to decide whether to activate; full instructions load only after activation.
Portable	The same SKILL.md works in Claude Code, Kiro, Cursor, Gemini CLI, Codex, etc.
Model-Invoked	Agent auto-selects the right Skill from task context — no manual specification.
Modular	Each Skill has a single responsibility; multiple Skills combine.
Scoped	Personal level (`~/.xxx/skills/`), project level (`.xxx/skills/`), or plugin distribution.
Security	`allowed-tools` restricts which tools a Skill can access (e.g., read-only, specific file types).
Self-Documenting	SKILL.md is itself human-readable — no extra docs needed.

(2) Typical Use Cases

Encoding team conventions: code style, commit-message format, PR review checklist
Multi-step workflows: deployment pipelines, data-analysis pipelines, report generation
Code-generation templates: unit-test generation, API scaffolding, documentation generation
DevOps automation: CI/CD pipeline configs, security scanning, log analysis
Knowledge consolidation: turn team best practices into executable Skills; new-hire onboarding plug-and-play

1.3. Competitors & Alternatives

Approach	Position	Pros	Cons
Agent Skills (SKILL.md)	Open standard, cross-platform	Portable, 20+ platforms, active community	No built-in version-control API
Cursor Rules (`.cursorrules`)	Cursor-only global rules	Simple, global	Single file, no modules, not portable
GitHub Copilot Instructions	Copilot-specific instructions	Deep GitHub integration	Platform locked
MCP (Model Context Protocol)	Tools and data-source protocol	Real-time data, bidirectional	Tool-call focused, not an instruction bundle
Manual System-Prompt injection	The most primitive way	Zero entry barrier; works on any LLM	Not reusable, manual every time, token-wasteful
Semantic Kernel Plugin	Microsoft AI orchestration framework	Code-level integration, type-safe	Language-bound (C#/Python), not portable
LangChain Tools	OSS Agent framework	Flexible, rich ecosystem	Framework-bound, steep learning curve

Trend: Agent Skills is becoming the de-facto standard. By mid-2026, Claude Code, VS Code (Copilot), Cursor, Gemini CLI, OpenAI Codex, Windsurf, Roo Code, Cline, Goose, and Kiro all support it.

2. Concept, Component, & Architecture

2.1. Key Concepts

(1) SKILL.md — the heart of a Skill

Each Skill is a folder containing a SKILL.md file.
SKILL.md has two parts:
YAML frontmatter: metadata (name, description, etc.) — the Agent uses this to decide whether to activate.
Markdown body: detailed instructions, workflow steps, examples — loaded only on activation.
This is Progressive Disclosure — minimize context usage, load on demand.

(2) Frontmatter Metadata Fields

Field	Required	Description
name	Yes	Unique identifier; lowercase + hyphens; up to 64 chars
description	Yes	Functional description; up to 1024 chars (Claude.ai limits 200); the basis for Agent matching
license	No	License name or reference
compatibility	No	Environment requirements (specific tools, network access, etc.)
metadata	No	Additional key-value pairs (author, version, etc.)
dependencies	No	Required packages
allowed-tools	No	Glob patterns restricting which tools are accessible (Claude Code-specific)

(3) Progressive Disclosure

The most elegant design in the Skill system, solving the "limited context window" tension:

Level 0 — Discovery
  At startup, only the name + description of every Skill is loaded (~hundreds of tokens).
  ↓
Level 1 — Activation
  When a user request matches a Skill's description → load the full SKILL.md.
  ↓
Level 2 — Deep Loading
  If SKILL.md references files in references/ or scripts/ → load those on demand.

Comparison: stuffing all instructions into the System Prompt with 10 Skills could cost 50K+ tokens; with Progressive Disclosure, typically only 3-5K tokens.

(4) Skill Scope

Global Scope
  ~/.kiro/skills/      (Kiro)
  ~/.claude/skills/    (Claude Code)
  ~/.hermes/skills/    (Hermes Agent)
  → Active across all projects; great for personal workflows.

Project Scope
  .kiro/skills/        (Kiro)
  .claude/skills/      (Claude Code)
  → Versioned with the repo; great for team conventions.

Plugin Scope
  → Distributed via marketplace or community; great for public Skills.

Priority: Project Scope > Global Scope (project Skills override global ones with the same name).

(5) Skill vs Function Calling vs MCP

Dimension	Skill (SKILL.md)	Function Calling	MCP
Essence	Instruction bundle (how to do it)	Tool definition (what can be called)	Tool + data-source protocol
Format	Markdown + YAML	JSON Schema	JSON-RPC
Transport	File system, on-demand	Schema sent every request	Real-time bidirectional
Abstraction	High (workflow level)	Low (single function)	Medium (tool-set level)
Portability	20+ platforms	Platform-specific schema	Cross-platform (needs server)
Token cost	Low (progressive loading)	High (schema repeated)	Medium (tools loaded once)
Best fit	Workflows, conventions, templates	API calls, data queries	External system integration, real-time data

The three are complementary, not substitutes: Skill defines "how", Function Calling provides "what can be done", MCP connects "external resources".

2.2. Core Components

(1) SKILL.md File

Required; the entry and core of a Skill.
Contains metadata (frontmatter) + instructions (Markdown body).
The Agent uses the description field to decide when to activate.

(2) `scripts/` directory (optional)

Houses executable code (Python, Shell, JS, etc.).
Best for deterministic tasks: input validation, file generation, API calls.
The Agent invokes scripts following SKILL.md's instructions.

(3) `references/` directory (optional)

Supplementary documentation and reference material.
Loaded only when SKILL.md references them — extending Progressive Disclosure.
Best for: detailed specs, sample data, config templates.

(4) `assets/` directory (optional)

Templates, charts, data files, and other static resources.
Best for: code templates, config-file templates, architecture diagrams.

2.3. Architecture & Design

(1) Skill Loading Flow

sequenceDiagram
  participant U as User
  participant A as AI Agent
  participant SI as Skill Index
  participant SM as SKILL.md
  participant R as References / Scripts

  Note over A,SI: At startup: load every Skill's name + description
  U->>A: Send request
  A->>SI: Match request against Skill descriptions
  SI-->>A: Return matched Skill
  A->>SM: Load full SKILL.md
  SM-->>A: Return instructions
  A->>R: Load scripts / references on demand
  R-->>A: Return resources
  A->>U: Execute per Skill instructions and return result

(2) Skill's Position in the Agent System

block-beta
  columns 1
  block:runtime["AI Agent Runtime"]
    columns 1
    block:prompt["System Prompt"]
      columns 1
      A["Agent Identity / SOUL.md"]
      B["Skills Index (name + description) ← Progressive Disclosure L0"]
      C["Memory / Context"]
      D["Conversation History"]
    end
    block:tools["Tool Layer"]
      columns 1
      E["Built-in Tools (file, terminal, web)"]
      F["MCP Server Tools"]
      G["Function Calling Definitions"]
    end
    block:skills["Skill Layer (activated on demand) ← Progressive Disclosure L1-L2"]
      columns 1
      H["SKILL.md (full instructions)"]
      I["scripts/ (executable code)"]
      J["references/ (supplementary docs)"]
    end
  end

2.4. Eco-system

(1) Supported Platforms (mid-2026)

Platform	Type	Skill location	Notes
Claude Code	CLI Agent	`~/.claude/skills/`, `.claude/skills/`	Native support; standard author
Claude.ai	Web/Desktop	Upload ZIP via UI	description limited to 200 chars
Kiro	IDE (VS Code)	`~/.kiro/skills/`, `.kiro/skills/`	Supports import, slash-command invocation
Cursor	IDE	`.cursor/skills/`	Compatible with Agent Skills
VS Code (Copilot)	IDE	`.github/skills/`	Via Agent Skills SDK
Gemini CLI	CLI Agent	`.gemini/skills/`	Native Google support
OpenAI Codex	CLI Agent	`.codex/skills/`	Native OpenAI support
Hermes Agent	CLI Runtime	`~/.hermes/skills/`	Self-evolving + 118 bundled Skills
Windsurf / Roo Code	IDE	Per-tool path	Community adapters

(2) Skill Sources & Community

Source	URL / Description
agentskills.io	Official spec and Skill directory
skill.md	Skill discovery and sharing platform
GitHub search	Search for `SKILL.md` or `agent-skills`
LobeHub Skills Market	lobehub.com/skills
Hermes Skills Hub	Aggregates 7+ sources (Official, skills.sh, GitHub)
Claude Marketplace	Built-in Skill marketplace in Claude.ai
explainx.ai	Skill browsing and search

3. Install, Configure, Secure, & Implementation

3.1. Skill Directory Structure (general)

my-skill/
├── SKILL.md           # Required: metadata + instructions
├── scripts/           # Optional: executable code
│   └── validate.py
├── references/        # Optional: supplementary docs
│   └── style-guide.md
└── assets/            # Optional: templates and resources
    └── template.yaml

3.2. Writing SKILL.md

---
name: my-skill-name
description: >
  One-sentence summary of what this Skill does and when it should activate.
  Include trigger keywords so the Agent can match accurately.
---

## Purpose
Briefly describe goal and applicable scenarios.

## Workflow
1. Step 1: specific action
2. Step 2: specific action
3. Step 3: specific action

## Examples
Concrete input → expected output.

## Edge Cases
How to handle special situations.

Full SKILL.md example (Data Analysis Skill):

---
name: data-analysis
description: >
  Perform statistical analysis and visualization on datasets.
  Use when asked to analyze data, generate charts, detect anomalies,
  or produce summary statistics.
dependencies:
  - python: ">=3.8"
  - pandas: ">=1.3.0"
---

## Overview
This skill provides advanced data analysis capabilities.

## When to Use
- Statistical analysis (mean, variance, quartiles)
- Data visualization (charts, plots)
- Anomaly detection

## When NOT to Use
- Real-time streaming data
- Datasets exceeding 1GB (use batch processing instead)

## Workflow
1. Read the input dataset
2. Run `scripts/validate.py` to check data format
3. Perform analysis based on user request
4. Generate visualization if requested
5. Return results in structured JSON format

## Output Format
Return JSON:
  {
    "summary": {...},
    "statistics": {...},
    "visualizations": [...]
  }

## Troubleshooting
- OutOfMemoryError → Use the batch_size parameter
- InvalidDataFormat → Ensure input is CSV/JSON with headers

Best practices when writing:
Precise description: include trigger keywords. "Review pull requests for security and test coverage" beats "helps with code review".
Keep SKILL.md focused: detailed docs go to references/; keep SKILL.md to the core instructions.
Use scripts for deterministic tasks: validation, file generation, API calls — use scripts/ instead of asking the LLM to regenerate.
Provide concrete examples: input/output examples help the Agent understand what success looks like.
Single responsibility: each Skill does one thing; multiple Skills compose.

3.3. Three-Platform Skill Walkthroughs

(1) Hermes Agent Skills

Hermes is the most differentiated — it supports Agent self-creation and self-improvement of Skills. - Path: ~/.hermes/skills/ - Format: follows the agentskills.io open standard, Markdown. - v0.10.0 ships with 118 bundled Skills.

Three sources of Hermes Skills: 1. Agent self-creation: after completing complex tasks (5+ tool calls), the Agent analyzes the steps, extracts reusable patterns, and writes a Skill automatically. 2. Manual authoring: a user writes one in the standard format. 3. Community install: from Skills Hub, skills.sh, GitHub, etc.

Example Hermes SKILL.md:

---
name: python-data-pipeline
description: >
  Build and debug Python data pipelines using pandas, SQLAlchemy,
  and Airflow. Use when asked to create ETL workflows, data
  transformations, or pipeline debugging.
---

## Context
End-to-end data pipeline development on macOS / Linux.

## Workflow
1. Assess data sources and target schema
2. Write extraction logic with error handling
3. Implement transformations using pandas
4. Set up SQLAlchemy connections with connection pooling
5. Create Airflow DAG for orchestration
6. Add monitoring and alerting

## Patterns
- Always use `with` context managers for DB connections
- Chunk large datasets: `pd.read_sql(..., chunksize=10000)`
- Log every stage transition for debugging

## Anti-patterns
- Never hardcode credentials; use environment variables
- Avoid loading entire dataset into memory

Hermes' Progressive Loading (consistent with the standard plus extensions):

# Level 0: list (~3K tokens)
skills_list()                    # → returns name + description for every Skill

# Level 1: full content (on demand)
skill_view("python-data-pipeline")  # → returns full SKILL.md + metadata

# Level 2: referenced files (on demand)
skill_view("python-data-pipeline", "references/airflow-patterns.md")

Hermes' self-improvement loop:

Agent uses Skill to complete a task
  ↓
Evaluate execution outcome
  ↓
skill_manage(action="patch", name="python-data-pipeline",
             patch="Add retry logic pattern for flaky API calls")
  ↓
Skill is incrementally updated; next use includes the new pattern

Hermes Skill management commands:

hermes skills list                                    # list all Skills
hermes skills view python-data-pipeline               # view a specific Skill
hermes skills install official/devops/docker-compose  # install from Hub
hermes skills install github:user/repo/skill-name     # install from GitHub
hermes skills export python-data-pipeline             # export
hermes skills delete python-data-pipeline             # delete

(2) Kiro Skills

Kiro is the AWS Agentic IDE, with full Agent Skills support. - Paths: - Project: .kiro/skills/ - Global: ~/.kiro/skills/ - Project-level overrides global-level on name conflict. - Supports import from GitHub and local folders.

Example Kiro SKILL.md:

---
name: pr-review
description: >
  Review pull requests for code quality, security issues, and
  test coverage. Use when reviewing PRs or preparing code for review.
---

## Review Process
1. Check for security vulnerabilities
2. Verify error handling
3. Confirm test coverage
4. Review naming and structure

## Security Checks
- No hardcoded credentials
- Input validation on all user-facing endpoints
- SQL parameterization
- XSS prevention in templates

## Output Format
Provide findings grouped by severity:
- CRITICAL: must fix before merge
- MAJOR: should fix; can be a follow-up
- MINOR: style and convention issues

Using Kiro Skills: - Auto-activation: Kiro matches the request against Skill descriptions. - Manual invocation: type / in chat to see available Skills, then pick one. - Management UI: see and manage in the Kiro Panel's "Agent Steering & Skills" section.

Importing a Kiro Skill: 1. Open Kiro Panel → Agent Steering & Skills 2. Click + → Import a skill 3. Choose source: - GitHub: paste a URL pointing to the Skill folder or SKILL.md (must be a sub-directory, not the repo root) - Local folder: pick from the local file system

Creating a Kiro Skill (via the IDE):

# Method 1: manual
mkdir -p .kiro/skills/my-skill
# Edit .kiro/skills/my-skill/SKILL.md

# Method 2: via Kiro Panel UI
# Agent Steering & Skills → + → Create a skill

(3) Claude Skills (Claude Code & Claude.ai)

Claude is the standard's author with the most complete support. - Claude Code (CLI) paths: - Personal: ~/.claude/skills/ - Project: .claude/skills/ - Claude.ai (Web/Desktop): upload a ZIP via UI.

Example Claude Code SKILL.md (with allowed-tools):

---
name: test-generator
description: >
  Generate comprehensive unit tests for JavaScript and TypeScript
  functions. Use when asked to write tests, create test suites,
  or improve test coverage.
allowed-tools:
  - Read
  - Glob
  - Grep
  - "Bash(npm test*)"
  - "Write(*.test.ts)"
  - "Write(*.test.js)"
---

## Purpose
Generate Jest unit tests covering happy paths, edge cases, and error conditions.

## Workflow
1. Read the target source file
2. Extract function signatures and understand logic
3. Identify test scenarios:
   - Happy path: valid inputs, typical use cases
   - Edge cases: null, undefined, empty, boundary values
   - Error handling: invalid inputs, exceptions
4. Generate test file following `*.test.{js|ts}` naming
5. Run tests with `npm test` and report results

## Test Structure
  describe('functionName', () => {
    describe('Happy Path', () => {
      it('should handle typical input', () => { ... });
    });
    describe('Edge Cases', () => {
      it('should handle empty input', () => { ... });
    });
    describe('Error Handling', () => {
      it('should throw on invalid input', () => { ... });
    });
  });

## Quality Standards
- Minimum 80% code coverage
- Descriptive test names
- Proper mocking of external dependencies
- Setup/teardown for shared fixtures

Claude Code's allowed-tools security control:

allowed-tools:
  - Read              # read-only files
  - Glob              # file search
  - Grep              # content search
  - "Bash(npm test*)" # only allow `npm test ...`
  - "Write(*.test.ts)" # only allow writing test files

Claude Code-specific security mechanism that restricts the Skill's tool scope.
Prevents a Skill from accidentally modifying production code or running dangerous commands.

Claude.ai Skill upload (Web/Desktop):

ZIP structure
my-skill.zip
└── my-skill/
    ├── SKILL.md       # required
    └── references/    # optional
        └── guide.md

Notes
- ZIP must contain a wrapping directory; can't drop files at the root
- description limited to 200 chars (vs. 1024 in the standard)
- Max ZIP: 50 MB
- Max file count: 500
- Max single file: 25 MB (uncompressed)

Claude Code's three deployment modes:

Personal Skills (~/.claude/skills/)
  → Personal workflows; active across projects
  → e.g., your commit-message style, code-review habits

Project Skills (.claude/skills/)
  → Team conventions; versioned in Git
  → e.g., project deployment flow, API design conventions

Plugin Skills (distributed via Claude Code Plugin)
  → Community / marketplace
  → e.g., framework-specific Skills, industry Skills

3.4. Security Best Practices

Skill development checklist:
[ ] No hard-coded credentials in SKILL.md (API keys, tokens, passwords)
[ ] Use allowed-tools to restrict tool access (Claude Code)
[ ] Code in scripts/ validates inputs
[ ] Comprehensive error handling that doesn't leak sensitive info
[ ] Doesn't modify system files or production data accidentally
Skill usage checklist:
[ ] Audit source: only install Skills from trusted sources
[ ] Review content: read SKILL.md, confirm no malicious operations
[ ] Restrict permissions: use allowed-tools to bound the Skill
[ ] Monitor execution: watch the Agent's tool-call logs
Hermes Agent extra security:
All Skills installed from the Hub are checked for data exfiltration, prompt injection, and destructive commands.
Trust hierarchy: builtin > official > trusted > community.
Memory writes pass through injection detection, credential-leak detection, and SSH-backdoor detection.

3.5. Cheatsheets

(1) Quickly Create a Skill (general)

# Create folder
mkdir -p .kiro/skills/my-skill            # Kiro project-level
# or
mkdir -p ~/.claude/skills/my-skill        # Claude Code personal
# or
mkdir -p ~/.hermes/skills/my-skill        # Hermes

# Create SKILL.md
cat > .kiro/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: Brief description of what this skill does and when to use it.
---

## Instructions
Your detailed instructions here.
EOF

(2) Skill Path Quick Reference

Platform	Personal	Project
Kiro	`~/.kiro/skills/`	`.kiro/skills/`
Claude Code	`~/.claude/skills/`	`.claude/skills/`
Hermes	`~/.hermes/skills/`	N/A (mostly global)
Cursor	N/A	`.cursor/skills/`
Gemini CLI	N/A	`.gemini/skills/`

(3) Hermes Skill Management Quick Reference

hermes skills list                    # list all
hermes skills view <name>             # view content
hermes skills install <source>        # install
hermes skills delete <name>           # delete
hermes skills export <name>           # export

4. Bootcamp & Workshops

4.1. Learning Resources

Resource	Type	Audience
Agent Skills Specification	Official spec	Everyone
Claude Skills How-To	Official guide	Claude users
Kiro Skills Docs	Official docs	Kiro users
Agent Skills 101	Practical guide	Engineers
Build Your First Skill (freeCodeCamp)	Tutorial	Beginners
Claude Code Skills Guide (fp8.co)	Deep guide	Senior engineers
Agent Skills SDK (Microsoft)	SDK docs	VS Code users

4.2. Trouble Shooting

(1) Skill not activated

Cause: description not specific enough; missing trigger keywords.
Fix: include concrete trigger phrases — "Use when asked to write tests" beats "helps with testing".
Verify: check Agent thinking/reasoning logs to confirm Skill recognition.

(2) Skill activates but behaves unexpectedly

Cause: SKILL.md instructions not specific enough or missing examples.
Fix: add an Examples section showing input → output flow.
Tip: use numbered steps rather than vague descriptions; the Agent follows them better.

(3) YAML frontmatter parse error

Cause: YAML syntax error (indentation, quotes, special chars).
Fix: validate via a YAML linter; ensure --- separators are correct.
Common pitfall: descriptions with colons need quoting.

(4) Skill file not discovered

Cause: wrong path or filename casing.
Fix: confirm SKILL.md (case-insensitive but uppercase recommended) is in the proper skills directory.
Note: the Skill folder name must match the name in the frontmatter.

(5) Cross-platform incompatibility

Cause: used a platform-specific field (e.g., Claude Code's allowed-tools).
Fix: keep core instructions standard-compatible; use platform-specific fields as optional enhancements.
Recommendation: validate on one platform first, then adapt to others.

4.3. Q & A

How is a Skill different from a System Prompt?
System Prompt is global and loads every conversation; a Skill is on-demand and only activates on match.
System Prompt is for general behavior constraints; Skills are for specific workflows.
The two coexist: System Prompt defines "who you are"; Skills define "how to do specific tasks".
How big should a Skill be?
SKILL.md: 50-200 lines is recommended; longer dilutes Agent attention.
Long content goes to references/ for on-demand loading.
If a Skill exceeds 300 lines, consider splitting into multiple Skills.
Can a Skill call another Skill?
Not explicitly, but the Agent can activate multiple Skills simultaneously and combine them.
This implicit composition is by design, not a limitation.
Difference between Hermes self-evolving Skills and manual Skills?
Self-evolving Skills are auto-created and refined by the Agent after complex tasks.
Manual Skills are user-authored and are not modified by the Agent.
The format is identical — they're interchangeable.
Unique value of self-evolving Skills: the Agent remembers "how" (Procedural Memory), not just "what".
When do you write a Skill vs. install an MCP?
One-liner: a Skill is the operations manual for the Agent; an MCP is external hands and feet connected to the Agent.
Write a Skill when teaching the Agent how to do something:
- Team conventions: commit-message format, code-review checklist, PR template
- Multi-step workflows: "first check logs, then locate the error, then generate a fix"
- Knowledge consolidation: deployment flow, onboarding steps, data-analysis recipes
- Output templates: report format, doc structure, code scaffolds
Install an MCP when giving the Agent something to do:
- Connect external systems: query DBs, call APIs, read files, operate GitHub
- Real-time data: pipeline status, monitoring metrics, log search
- Take actions: send email, create tickets, trigger deployments
Combine both (most common, most powerful): the Skill says "step 1: search code via GitHub; step 2: analyze; step 3: produce report"; the MCP provides the GitHub search capability; the Agent follows the Skill's flow using the MCP's tools.
Heuristic: if you write "please look up XXX data" inside a Skill, the lookup capability should come from MCP. If the Agent has tools but doesn't know when to use them — write a Skill.
See §2.1(5) above for the three-way comparison and 4.Protocol/2.MCP.md for detailed MCP notes.
Is SKILL.md a "manifest file" listing all Skills?
No — common misconception. There's no top-level index file.
Actual structure: each Skill is a separate folder; the folder's SKILL.md is that Skill. ``` ❌ Wrong mental model (declarative registration) skills/ ├── SKILL.md ← thinking this is a manifest listing all skills ├── math-helper.md └── code-review.md

✅ Correct structure (convention-based discovery) skills/ ├── math-helper/ │ └── SKILL.md ← this IS the math-helper skill ├── code-review/ │ └── SKILL.md ← this IS the code-review skill └── deploy-guide/ └── SKILL.md ← this IS the deploy-guide skill `` -SKILL.mdis a fixed filename, likepackage.jsonfor a Node.js package. - The "index" is auto-managed by the Agent runtime: at startup it scans every subfolder underskills/, finds eachSKILL.md, reads only its frontmatter (name+description), and builds an in-memory index — Progressive Disclosure Level 0. - Conceptual difference: "declarative registration" (manifest lists all components) vs. "convention-based discovery" (auto-scan by directory). Agent Skills uses the latter — similar to Spring Boot auto-scan or Pythoninit.py` discovery.
Is a Skill just a bunch of executable scripts? What is scripts/ exactly?
No — another common misconception. People think Skill = executable scripts and SKILL.md = the API doc for those scripts.
The actual relationship is the opposite: ``` ❌ Wrong mental model Skill = hands & feet (a bunch of shell/python functions) SKILL.md = parameter docs (telling the Agent how to call those scripts)

✅ Correct understanding SKILL.md = brain instructions (natural-language workflow telling the Agent: when X happens, do steps 1-2-3) Agent's existing Tools = hands & feet (file I/O, terminal, browser, MCP tools, etc.) scripts/ = optional tool extensions (deterministic logic you don't want the LLM to regenerate every time) - `scripts/` is good for deterministic tasks: input validation, file scaffolding, API call wrappers, format conversion. - `scripts/` is bad for: business judgment (let the Agent reason), creative content (let the Agent generate). - How does the Agent use scripts? SKILL.md says "run `scripts/validate.py` to check the config"; the Agent uses its existing terminal tool to execute it. Scripts are not the entry point — they are resources callable from instructions. - How to extend `scripts/`: just create the directory under the Skill folder, drop scripts in, and reference them in SKILL.md. The Agent will execute them via terminal tools (Bash/Shell): my-skill/ ├── SKILL.md ← "Step 3: run scripts/lint.sh to check code style" └── scripts/ └── lint.sh ← Agent runs this via the terminal tool `` - Where are the Agent's "hands and feet" (Built-in Tools)? See4.HermesAgent.mdand2.Application/3.Agent.md` "Built-in Tools" section. Tools are runtime capabilities (file I/O, terminal, browser) — not part of a Skill. A Skill only tells the Agent how to use those Tools; MCP is the protocol for adding more Tools.
Different platforms have different Built-in Tools and MCP Servers — does the same Skill need different code on different platforms?
In most cases, no — that's the entire point of Skills.
The core of a Skill is natural-language instructions (the SKILL.md Markdown body), not code. "First search relevant code, then analyze, then produce a report" is understood on Kiro, Claude Code, Gemini CLI, and Hermes alike — the Agent uses its platform's Built-in Tools to execute.
Edge cases to watch:
- Markdown instructions: cross-platform, no changes needed. This is the core value of the agentskills.io open standard.
- scripts/ directory: scripts themselves (Python/Shell) are cross-platform. Different platforms have different terminal tool names (Kiro's executeBash vs. Hermes's terminal), but the Agent adapts automatically.
- Platform-specific frontmatter fields: e.g., Claude Code's allowed-tools. Other platforms ignore the field — harmless but inactive. Recommendation: keep core instructions standard-compatible; use platform-specific fields as optional enhancements.
Compare with Agent code: an Agent's code is platform-bound — LangGraph is a Python graph definition; CrewAI is a role definition; Kiro is Spec-driven. Different programming models entirely. There is no open standard like Skills for Agents.
One-line summary: Skills are "natural language for the AI to read" — naturally cross-platform; Agents are "code for a framework to run" — naturally platform-bound.
See §1.2(1) "Portable" feature, and §3.3 three-platform comparison.
How do I use a Skill in the Gemini ecosystem?
Gemini CLI natively supports Agent Skills — drop into .gemini/skills/.
Gemini API (non-CLI): inject SKILL.md content as system_instruction, alongside Function Calling.
Context Caching: for many Skills, use Gemini's caching to lower cost.

import google.generativeai as genai
# Use Skill content as system_instruction
skill_content = open("./skills/my-skill/SKILL.md").read()
model = genai.GenerativeModel(
  model_name='gemini-2.5-pro',
  system_instruction=skill_content,
  tools=tools_list  # paired with Function Calling
)