Files
skillshare/website/docs/reference/commands/new.md
T
Willie cf36965cea feat(website): add zh-Hant/zh-Hans/ja/ko locales with initial docs translation
Sets up Docusaurus i18n for Traditional Chinese, Simplified Chinese,
Japanese, and Korean: locale config, navbar/footer/sidebar UI chrome,
and translated content for intro, getting-started, understand, and
reference/commands. Untranslated pages fall back to English.

Pins explicit heading anchors ({#id}) on English source pages that are
linked to by fragment, so translated headings don't change the anchor
id and break cross-page links. Converts a handful of relative .md
links that crossed from an untranslated page into a now-translated
one, since Docusaurus resolves those per-locale and they'd otherwise
404 outside English.
2026-09-20 11:08:48 +08:00

6.8 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/)
--pattern, -P Use a design pattern (tool-wrapper, generator, reviewer, inversion, pipeline, none)
--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 ...
---
...

Pattern Templates

Use -P to generate a pattern-specific template with recommended directory structure:

skillshare new my-reviewer -P reviewer     # Reviewer pattern
skillshare new my-pipeline -P pipeline     # Pipeline with references/, assets/, scripts/
skillshare new my-skill                    # Interactive TUI to choose

Available patterns:

Pattern Scaffold Directories
tool-wrapper references/
generator assets/, references/
reviewer references/
inversion assets/
pipeline references/, assets/, scripts/
none (plain template, no directories)

See Skill Design Patterns for details on each pattern.


Web UI Wizard

You can also create skills from the web dashboard — no terminal needed.

  1. Run skillshare ui
  2. Navigate to Skills → click "+ New Skill"
  3. Follow the wizard:
Step What
Name Enter skill name with real-time validation
Pattern Choose from 6 design patterns (card grid)
Category Pick a domain category — skipped if pattern is none
Scaffold Toggle recommended directories — skipped if pattern has no dirs
Confirm Review selections and create

The wizard follows the current mode — if the dashboard is running in project mode (-p), the skill is created in .skillshare/skills/.


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

See Also