SKILL.md: A Standard Format for Distributable AI Agent Skills

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:

1. Human-Readable: Non-technical stakeholders can understand the skill's purpose by reading the first few lines. No need to parse JSON.

2. Git-Friendly: Diffs are meaningful. You can see exactly what changed in a skill update without needing specialized tools.

3. Easy to Edit: Markdown files work in any text editor. GitHub's web interface renders them beautifully. There's no syntax barrier.

4. Agents Already Understand Markdown: Most LLMs have seen millions of markdown files during training. They parse it naturally.

5. 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:

1. Directory Scanning: Agents scan known skill repositories
2. Registry Lookup: Central registries maintain skill metadata (like npm)
3. URL-Based Loading: Direct SKILL.md files by URL

When an agent needs a capability, it:

1. Searches for matching skills (by tags, keywords)
2. Loads the SKILL.md file
3. Parses metadata and schemas
4. 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

1. Star the Repository: Show support by starring https://github.com/tancoai/lianzhu-skill

2. Create Your Own Skill: Fork the repo, write your own SKILL.md file following the format, and submit a pull request.

3. Share Your Use Cases: Have an idea for a skill? Open an issue and describe it.

4. 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.