When we talk about "AI skills", most people think of prompts. But prompts are not distributable, versionable, or discoverable. SKILL.md solves this.
What is SKILL.md?
SKILL.md is a structured markdown format that allows AI agents to discover, load, and execute skills dynamically. Think of it as a universal package format for AI capabilities—similar to how npm packages work for JavaScript or PyPI packages for Python, but designed from the ground up for agent-to-agent consumption.
Each SKILL.md file contains everything an agent needs:
- Metadata: name, version, description, tags
- System Prompt: the behavioral instructions
- Input Schema: what parameters the skill accepts
- Output Schema: what the skill returns
- Examples: real-world usage patterns
Format Anatomy: Inside a SKILL.md File
A typical SKILL.md follows this structure:
# Skill Name
**Version**: 1.0.0
**Tags**: category, use-case
**Description**: What this skill does and why an agent might need it.
## System Prompt
Your role is to [primary function]. When handling tasks:
- Consider [important constraint 1]
- Always [important behavior 1]
- Return [output format]
## Input Schema
json
{
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "What this parameter does"
}
},
"required": ["param_name"]
}
## Output Schema
json
{
"type": "object",
"properties": {
"result": {
"type": "string",
"description": "The skill's output"
}
}
}
## Examples
### Example 1: Basic Usage
**Input**: `{"param": "value"}`
**Output**: `{"result": "expected output"}`
### Example 2: Complex Case
**Input**: `{"param": "another value"}`
**Output**: `{"result": "complex output"}`
plaintext
Why Markdown Over JSON/YAML?
We chose markdown because:
Human-Readable: Non-technical stakeholders can understand the skill's purpose by reading the first few lines. No need to parse JSON.
Git-Friendly: Diffs are meaningful. You can see exactly what changed in a skill update without needing specialized tools.
Easy to Edit: Markdown files work in any text editor. GitHub's web interface renders them beautifully. There's no syntax barrier.
Agents Already Understand Markdown: Most LLMs have seen millions of markdown files during training. They parse it naturally.
Extensible: You can add custom sections without breaking existing parsers. JSON/YAML schemas don't degrade gracefully.
Three Real Examples at Different Complexity Levels
Example 1: Simple Naming Skill
This skill generates product names based on target audience and category.
Input: audience ("tech professionals" or "parents"), category ("software" or "toy")
Output: A list of 5 creative product names
Use Case: Startups naming their first product; marketing teams brainstorming.
Example 2: Copywriting Diagnosis Skill
This skill analyzes marketing copy and identifies engagement weaknesses—passive voice, weak verbs, missing urgency signals.
Input: Marketing copy (any length), target audience
Output: JSON object with findings:
- Passive voice: 3 instances (lines 2, 5, 8)
- Weak verbs: 2 instances
- Missing urgency: yes/no
- Recommended improvements: [list]
Use Case: Copywriters iterating on email campaigns; content teams scaling their output.
Example 3: Ziwei Astrology Chart Skill
This skill generates personalized astrology readings based on birth date, time, and location—applying classical Ziwei principles.
Input: Birth datetime (ISO format), location (coordinates), reading type ("personality" or "career")
Output: Detailed astrology report with palace interpretations, strength indices, key life themes.
Use Case: Astrology platforms, personalized content engines, wellness apps.
How Agents Discover and Load Skills
Agents locate skills through directory conventions:
/skills
/naming
SKILL.md ← Agent reads this file
/copywriting
SKILL.md
/ziwei-astrology
SKILL.md
Discovery patterns include:
- Directory Scanning: Agents scan known skill repositories
- Registry Lookup: Central registries maintain skill metadata (like npm)
- URL-Based Loading: Direct SKILL.md files by URL
When an agent needs a capability, it:
- Searches for matching skills (by tags, keywords)
- Loads the SKILL.md file
- Parses metadata and schemas
- Invokes the skill with validated inputs
Production-Ready: 50 Free Open-Source Skills
We've packaged 50 production-ready skills covering common tasks:
- Content Creation: copywriting, naming, outline generation
- Data Processing: CSV parsing, JSON transformation, filtering
- Analysis: sentiment analysis, text summarization, code review
- Automation: file organization, batch processing, scheduling
Repository: https://github.com/tancoai/lianzhu-skill
Browse the code, fork it, contribute improvements. All skills are open-source and MIT-licensed.
The SKILL.md Platform: 284 Skills (50 Free + Paid)
Beyond the open-source collection, the full SKILL.md marketplace hosts 284 verified skills:
Platform: https://tancoai.com
Access includes:
- Free tier: 50 skills + community contributions
- Paid tiers: Premium skills for specialized domains (finance, healthcare, creative services)
- API access: Integrate skills into your own applications
- Version control: Each skill is versioned and can be rolled back
Next Steps: How You Can Contribute
Star the Repository: Show support by starring https://github.com/tancoai/lianzhu-skill
Create Your Own Skill: Fork the repo, write your own SKILL.md file following the format, and submit a pull request.
Share Your Use Cases: Have an idea for a skill? Open an issue and describe it.
Integrate with Your Tools: Use skills in your AI agents, chatbots, or internal automation.
The SKILL.md standard is young, but it's solving real problems: how to make AI capabilities modular, shareable, and agent-discoverable. We'd love to have you contribute.
Questions? Check the repository README or join our community discussions on GitHub.
Top comments (0)