mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
Restructure the entire documentation site following the Diátaxis framework (Learn / How-to / Understand / Reference) with new content across 110 files. ## Information Architecture (M1) - Move all docs to Diátaxis directory structure (learn/, how-to/, understand/, reference/) - Add client-redirects plugin for old URL compatibility - Rewrite sidebar, navbar, and footer to match new IA - Update all internal cross-references ## Homepage + Quickstarts (M2) - Add scenario entry cards to homepage with hand-drawn design - 5 quickstart pages: Claude Code, GitHub Copilot (with copy mode recommendation), Codex, Multiple Tools, Dev Containers, Playground ## Blog + Changelog (M3) - Enable Docusaurus blog plugin with authors.yml - 5 blog posts: 5-min tutorial, managing 50+ skills, skillshare vs vercel/skills comparison, team sharing patterns, write your first skill - Static /changelog page from CHANGELOG.md ## Recipes + Philosophy (M4) - 5 recipe pages: CI/CD validation, enterprise skills, project setup, cross-machine sync, team onboarding - 3 philosophy pages: why-local-first, security-first, sync-modes-explained ## Content Polish - Cross-validate all content against CLI source (19 inaccuracies fixed) - Lowercase "skillshare" throughout (avoid brand conflict with Skillshare Inc.) - Add registry.yaml to file structure and Key Paths docs - Highlight multi-platform git support (GitHub, GitLab, Bitbucket, Gitea, Azure DevOps, AtomGit, Codeberg) - Standardize brew install command - Add AsciinemaPlayer component (cast recordings pending)
5.2 KiB
5.2 KiB
sidebar_position
| sidebar_position |
|---|
| 4 |
new
Create a new skill with a SKILL.md template.
skillshare new <name> # Create a new skill
skillshare new <name> -p # Create in project (.skillshare/skills/)
skillshare new <name> --dry-run # Preview without creating
When to Use
- Create a new skill from scratch with the recommended template structure
- Start with the correct SKILL.md format (name, description, frontmatter)
What happens:
flowchart TD
CMD["skillshare new my-skill"]
VALIDATE["1. Validate skill name"]
CREATE["2. Create skill directory"]
GENERATE["3. Generate SKILL.md template"]
CMD --> VALIDATE --> CREATE --> GENERATE
Options
| Flag | Description |
|---|---|
--project, -p |
Create in project (.skillshare/skills/) |
--global, -g |
Create in global (~/.config/skillshare/skills/) |
--dry-run, -n |
Preview without creating files |
--help, -h |
Show help |
Auto-detection: if .skillshare/config.yaml exists in the current directory, defaults to project mode.
Skill Name Rules
- Lowercase letters, numbers, hyphens, underscores
- Must start with a letter or underscore
- Examples:
my-skill,code_review,pdf-tools
Template Structure
The generated SKILL.md follows Anthropic's skill-building best practices:
---
name: my-skill
description: >-
Describe what this skill does. Use when user asks to
"trigger phrase 1", "trigger phrase 2", or needs help
with a specific task.
# ── Optional fields ──────────────────────────────────
# license: MIT
# allowed-tools: "Bash(python:*) WebFetch"
# metadata:
# author: Your Name
# version: 1.0.0
---
# My Skill
Brief overview of what this skill does and its value.
## When to Use
Use this skill when the user:
- Asks to "specific trigger phrase"
- Mentions specific keywords or file types
- Needs help with a particular task
Do NOT use this skill for:
- Unrelated tasks (clarify scope boundaries)
## Instructions
### Step 1: Gather Context
### Step 2: Execute
### Step 3: Validate
## Examples
**Example:** Common scenario
User says: "Help me with <my-skill-related task>"
## Troubleshooting
**Error:** Common error message
**Cause:** Why it happens
**Solution:** How to fix it
Key design choices
The template follows Anthropic's three-level progressive disclosure model:
| Level | What | Loaded when |
|---|---|---|
| 1. Frontmatter | name + description |
Always (system prompt) |
| 2. SKILL.md body | Full instructions | When skill is relevant |
| 3. Linked files | references/, scripts/ |
On demand |
Description must include WHAT + WHEN — This is the single most important field. Claude uses it to decide whether to load your skill. Bad: "Helps with projects". Good: "Manages sprint planning. Use when user says 'plan sprint' or 'create tickets'." See Anthropic's guide for more examples.
Examples
Create a simple skill
skillshare new code-review
Output:
New Skill Created
─────────────────────────────────────────────
✓ Created: ~/.config/skillshare/skills/code-review/SKILL.md
Next steps:
1. Edit ~/.config/skillshare/skills/code-review/SKILL.md
2. Run 'skillshare sync' to deploy
Create in a project
skillshare new code-review -p
Output:
New Skill Created (project)
─────────────────────────────────────────────
✓ Created: .skillshare/skills/code-review/SKILL.md
Next steps:
1. Edit .skillshare/skills/code-review/SKILL.md
2. Run 'skillshare sync' to deploy
Preview before creating
skillshare new my-skill --dry-run
Output:
New Skill (dry-run)
─────────────────────────────────────────────
→ Would create: ~/.config/skillshare/skills/my-skill
→ Would write: ~/.config/skillshare/skills/my-skill/SKILL.md
Template preview:
─────────────────────────────────────────────
---
name: my-skill
description: >-
Describe what this skill does. Use when user asks to ...
---
...
Next Steps
After creating a skill:
- Edit the SKILL.md — Focus on the
descriptionfield first (WHAT + WHEN) - Add instructions — Use step-based format with clear actions
- Sync to targets —
skillshare sync - Test triggering — Ask your AI CLI a related question and check if the skill loads
- Iterate — Refine trigger phrases based on over/under-triggering
See Also
- install — Install skills from repos
- sync — Sync skills to targets
- Configuration — Config reference