Claude Skills Configuration - Learning Notes

What Is It?

• Agent Skills are a lightweight, open format for extending AI agent capabilities.
• A skill is a folder of organized files consisting of instructions, scripts, assets and resources that agents can discover to perform a specific task accurately. At their core, skills are a collection of prompts and some script files — Claude reads the prompt instructions and uses them to invoke the script files to complete a task.

When Should You Create a Skill?

• If a use case needs to persist across sessions — for example, if a user gives a command in one conversation and the system needs to continue executing that command in future conversations — then creating a skill is a good approach.

The Design Philosophy Behind Skills

• Modularity: Break functionality into independent modules, each responsible for a specific task, making them easy to maintain and reuse.
• Progressive disclosure: Show relevant information or functionality only when the user needs it, avoiding information overload.
• On-demand loading: Load relevant resources or code only when the user needs to use a particular feature, improving performance and responsiveness.

• MCP is primarily used for fetching data.
• Tools (such as shell or Python scripts) are primarily used for processing data or executing specific tasks.
• Skills are a higher-level concept — they can contain multiple MCPs and Tools to deliver a complete feature.
• SubAgents are responsible for handling specific tasks and reporting results back to the main agent. A SubAgent can invoke its own MCPs and Tools to complete its work, but its output is ultimately consumed by the main agent.

Skill File Structure

A Claude Code Skill is essentially a Markdown file stored under ~/.claude/skills/. When a user invokes it via /skill-name, Claude reads the file’s content and executes it as instructions.

1
2
3
4
5
6

~/.claude/skills/
├── my-skill.md              # Single-file Skill (simplest form; all lowercase recommended, avoid Claude keywords)
├── my-skill/                 # Directory-form Skill (supports accompanying scripts)
    └── SKILL.md              # Required — the Skill's entry point file
    └── Reference/            # Optional script directory for files called by the Skill
        └── helper.sh         # Example script file  

• A skill can include not only Markdown files but also shell scripts, Python scripts, icons, images, and other asset files.

SKILL.md Format

Each Skill file consists of two parts: Front Matter (metadata, file header) and the body (instruction content).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: knowledge-importer
description: Converts PDF knowledge-base documents into Hexo Markdown format using AI-powered formatting
user-invocable: true          # Whether it can be manually invoked via /name; defaults to true
---

## Preset Skills
[Anthropics Skills](https://github.com/anthropics/skills)

## Tool Title

Write the detailed instructions Claude needs to execute here...

### Usage
...

Front Matter field reference:

Storage Locations and Scope

Both locations can coexist; project-level Skills are merged with global Skills.
The Skill body can reference script files, and Claude will invoke them via the Bash tool during execution.

Skill Installation

Looking at my own Skills, I noticed that some of the MCPs I had installed earlier also appear inside this Skill.

Best Practices

Commands

1

Use the skill-creator to evaluate how well my skills in @../custom_skills/ have followed the best practices. Use subagents in parallel,each subagent evaluates one.

You can use Claude’s built-in skill-creator directly to audit whether a given Skill follows the conventions.

Other Questions

What Is the Difference Between a Claude Code Skill and an OpenClaw Skill?

In short: Claude Code Skills are shortcut commands for developer tools; OpenClaw Skills are a plugin system for general-purpose AI agents with much broader coverage. The latter is an evolutionary development of the former’s philosophy.

Skill Portability Across the Claude Ecosystem

This discussion comes from Andrew Ng’s course on Bilibili. The video subtitles are rough, so it’s worth going straight to the notes instead.

The four Claude ecosystem products mentioned in the course map to the following:

This separation actually makes a lot of sense — it keeps different environments from interfering with each other.

Moving from Claude AI’s graphical interface to pure API programming does take some adjustment. But once you understand how the code execution tool and the Files API work together, you’ll find this programming model gives you unprecedented control. The graphical interface is great for quickly validating ideas; the API is what you reach for when building scalable, production-grade applications.

The sandboxed environment with no internet access looks like a constraint at first, but from a security standpoint it’s a sensible design. If you need network access, you can pre-download data outside the container or combine it with other APIs. Remember: constraints often push you toward more elegant solutions.

References

1. Andrew Ng’s Skills course (Bilibili)
2. Reference notes