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

242 lines
6.8 KiB
Markdown

---
sidebar_position: 4
---
# new
Create a new skill with a SKILL.md template.
```bash
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:**
```mermaid
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](https://www.anthropic.com/engineering/building-skills-for-claude):
```markdown
---
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](https://www.anthropic.com/engineering/building-skills-for-claude) 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](https://www.anthropic.com/engineering/building-skills-for-claude) for more examples.
---
## Examples
### Create a simple skill
```bash
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
```bash
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
```bash
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:
```bash
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](/docs/understand/philosophy/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
- [install](/docs/reference/commands/install) — Install skills from repos
- [sync](/docs/reference/commands/sync) — Sync skills to targets
- [Configuration](/docs/reference/targets/configuration) — Config reference