Files
skillshare/website/docs/commands/new.md
T
Willie 570195d1a2 feat: enhance skill template, improve search UX, and harden playground
- new: redesign SKILL.md template based on Anthropic's skill-building
  guide — description now includes WHAT+WHEN trigger format, step-based
  instructions (Gather/Execute/Validate), examples, and troubleshooting
- search: prompt for keyword when run without arguments instead of
  auto-browsing popular skills
- playground: default shell to $HOME (/sandbox-home) and mount source
  as read-only to prevent accidental host file modifications
2026-02-09 21:43:10 +08:00

7.1 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

What happens:

┌─────────────────────────────────────────────────────────────────┐
│ skillshare new my-skill                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. Validate skill name                                          │
│    → lowercase, numbers, hyphens only                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. Create skill directory                                       │
│    → ~/.config/skillshare/skills/my-skill/                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Generate SKILL.md template                                   │
│    → ~/.config/skillshare/skills/my-skill/SKILL.md              │
└─────────────────────────────────────────────────────────────────┘

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:

  1. Edit the SKILL.md — Focus on the description field first (WHAT + WHEN)
  2. Add instructions — Use step-based format with clear actions
  3. Sync to targets — skillshare sync
  4. Test triggering — Ask your AI CLI a related question and check if the skill loads
  5. Iterate — Refine trigger phrases based on over/under-triggering