mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 12:23:22 +00:00
- Guides: split 10 flat items into 3 sub-categories (Skills, Sharing, Advanced) - Workflows: move Troubleshooting Workflow into Troubleshooting category - Migration: add project mode sections (committed skills, global→project, team options) - Configuration: add audit section, project config format, custom audit rules - Navbar: add Guides and Targets quick links - Fix .skillshare.yaml → .skillshare-meta.json across all docs (wrong filename/format) - Bump font sizes site-wide for readability (base 16→17px, components proportional)
215 lines
3.8 KiB
Markdown
215 lines
3.8 KiB
Markdown
---
|
|
sidebar_position: 5
|
|
---
|
|
|
|
# Skill Format
|
|
|
|
The structure and metadata of a skillshare skill.
|
|
|
|
## Overview
|
|
|
|
A skill is a directory containing at least a `SKILL.md` file:
|
|
|
|
```
|
|
my-skill/
|
|
└── SKILL.md
|
|
```
|
|
|
|
The `SKILL.md` file has two parts:
|
|
1. **YAML frontmatter** — Metadata
|
|
2. **Markdown body** — Instructions for the AI
|
|
|
|
---
|
|
|
|
## Basic Structure
|
|
|
|
```markdown
|
|
---
|
|
name: my-skill
|
|
description: Brief description of what this skill does
|
|
---
|
|
|
|
# My Skill
|
|
|
|
Instructions for the agent when this skill is activated.
|
|
|
|
## When to Use
|
|
|
|
Describe when this skill should be used.
|
|
|
|
## Instructions
|
|
|
|
1. First step
|
|
2. Second step
|
|
3. Additional steps as needed
|
|
```
|
|
|
|
---
|
|
|
|
## Required Fields
|
|
|
|
### `name`
|
|
|
|
The skill identifier. Used for:
|
|
- Invoking the skill (e.g., `/skill:my-skill`)
|
|
- Collision detection
|
|
- Display in skill lists
|
|
|
|
```yaml
|
|
name: my-skill
|
|
```
|
|
|
|
**Rules:**
|
|
- Lowercase letters, numbers, hyphens, underscores
|
|
- Must start with a letter or underscore
|
|
- Should be unique across all skills
|
|
|
|
**Examples:**
|
|
```yaml
|
|
name: code-review
|
|
name: pdf-tools
|
|
name: acme:frontend-ui # Namespaced for teams
|
|
```
|
|
|
|
---
|
|
|
|
## Optional Fields
|
|
|
|
### `description`
|
|
|
|
Brief description shown in skill lists and search results.
|
|
|
|
```yaml
|
|
description: Reviews code for bugs, style issues, and improvements
|
|
```
|
|
|
|
---
|
|
|
|
## Custom Metadata
|
|
|
|
You can add any custom fields:
|
|
|
|
```yaml
|
|
---
|
|
name: my-skill
|
|
description: My custom skill
|
|
author: Your Name
|
|
version: 1.0.0
|
|
tags: [productivity, code-review]
|
|
---
|
|
```
|
|
|
|
These are stored but not used by skillshare itself.
|
|
|
|
---
|
|
|
|
## Markdown Body
|
|
|
|
The body contains instructions for the AI. Write it as if you're instructing a human assistant.
|
|
|
|
**Good practices:**
|
|
- Clear, specific instructions
|
|
- Examples of inputs and expected outputs
|
|
- Edge cases and error handling
|
|
- When to use (and when NOT to use)
|
|
|
|
**Example:**
|
|
```markdown
|
|
# Code Review
|
|
|
|
You are a code reviewer. Analyze code for:
|
|
- Bugs and potential issues
|
|
- Style and consistency
|
|
- Performance concerns
|
|
- Security vulnerabilities
|
|
|
|
## When to Use
|
|
|
|
Use this skill when the user asks you to review code, find bugs, or improve code quality.
|
|
|
|
## Instructions
|
|
|
|
1. Read the provided code carefully
|
|
2. Identify issues in order of severity
|
|
3. Suggest specific improvements with code examples
|
|
4. Be constructive and explain your reasoning
|
|
|
|
## Example
|
|
|
|
User: "Review this function"
|
|
```python
|
|
def add(a, b):
|
|
return a + b
|
|
```
|
|
|
|
Response: "The function looks correct but could benefit from type hints..."
|
|
```
|
|
|
|
---
|
|
|
|
## Skill Metadata File
|
|
|
|
When you install a skill, skillshare creates a `.skillshare-meta.json` file:
|
|
|
|
```json
|
|
{
|
|
"source": "anthropics/skills/skills/pdf",
|
|
"type": "github",
|
|
"installed_at": "2026-01-20T15:30:00Z",
|
|
"repo_url": "https://github.com/anthropics/skills.git",
|
|
"subdir": "skills/pdf",
|
|
"version": "abc1234"
|
|
}
|
|
```
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `source` | Original install source input |
|
|
| `type` | Source type (`github`, `local`, etc.) |
|
|
| `installed_at` | Installation timestamp |
|
|
| `repo_url` | Git clone URL (git sources only) |
|
|
| `subdir` | Subdirectory path (monorepo sources only) |
|
|
| `version` | Git commit hash at install time |
|
|
|
|
This is used by `skillshare update` and `skillshare check` to know where to fetch updates from.
|
|
|
|
**Don't edit this file manually.**
|
|
|
|
---
|
|
|
|
## Creating a Skill
|
|
|
|
```bash
|
|
skillshare new my-skill
|
|
```
|
|
|
|
This creates:
|
|
```
|
|
~/.config/skillshare/skills/my-skill/
|
|
└── SKILL.md (with template)
|
|
```
|
|
|
|
Edit the generated `SKILL.md` and run `skillshare sync` to deploy.
|
|
|
|
---
|
|
|
|
## Validating Skills
|
|
|
|
```bash
|
|
skillshare doctor
|
|
```
|
|
|
|
Checks for:
|
|
- Valid SKILL.md format
|
|
- Required `name` field
|
|
- Valid frontmatter YAML
|
|
- Name collisions
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- [Creating Skills](/docs/guides/creating-skills) — Step-by-step guide
|
|
- [Commands: new](/docs/commands/new) — Create command
|
|
- [Commands: doctor](/docs/commands/doctor) — Diagnose issues
|