Files
skillshare/website/docs/reference/commands/new.md
T
Willie caa525b8aa feat(website): complete website revamp — Diátaxis IA, blog, recipes, quickstarts
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)
2026-02-26 22:27:23 +08:00

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:

  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