@@ -101,7 +101,7 @@ These are auto-detected during `skillshare init`:
iflow
~/.iflow/skills
.iflow/skills
junie
~/.junie/skills
.junie/skills
kilocode
~/.kilocode/skills
.kilocode/skills
-
kimi
~/.kimi/skills
.agents/skills
+
kimi
~/.config/agents/skills
.agents/skills
kiro
~/.kiro/skills
.kiro/skills
kode
~/.kode/skills
.kode/skills
letta
~/.letta/skills
.skills
@@ -115,7 +115,7 @@ These are auto-detected during `skillshare init`:
pochi
~/.pochi/skills
.pochi/skills
qoder
~/.qoder/skills
.qoder/skills
qwen
~/.qwen/skills
.qwen/skills
-
replit
—
.agents/skills
+
replit
~/.config/agents/skills
.agents/skills
roo
~/.roo/skills
.roo/skills
trae
~/.trae/skills
.trae/skills
trae-cn
~/.trae-cn/skills
.trae/skills
@@ -133,11 +133,18 @@ Some targets have alternative names for backward compatibility or convenience:
| Alias | Resolves To | Notes |
|-------|-------------|-------|
+| `agents` | `universal` | Legacy name |
| `claude-code` | `claude` | Legacy name |
| `command-code` | `commandcode` | Hyphenated variant |
+| `deep-agents` | `deepagents` | Hyphenated variant |
+| `gemini-cli` | `gemini` | With CLI suffix |
| `github-copilot` | `copilot` | Full product name |
-| `opencode-ai` | `opencode` | With suffix |
-| `trae-cn` | `traecn` | Hyphenated variant |
+| `iflow-cli` | `iflow` | With CLI suffix |
+| `kilo` | `kilocode` | Short name |
+| `kimi-cli` | `kimi` | With CLI suffix |
+| `kiro-cli` | `kiro` | With CLI suffix |
+| `mistral-vibe` | `vibe` | Full product name |
+| `qwen-code` | `qwen` | With code suffix |
You can use either the alias or the canonical name in all commands:
diff --git a/website/docs/understand/declarative-manifest.md b/website/docs/understand/declarative-manifest.md
index 2a65196b2..07855ac71 100644
--- a/website/docs/understand/declarative-manifest.md
+++ b/website/docs/understand/declarative-manifest.md
@@ -4,7 +4,7 @@ sidebar_position: 7
# Declarative Skill Manifest
-Define your skill collection as code — install, share, and reproduce setups from a single config file.
+Define your skill collection as code — install, share, and reproduce setups from a single manifest file.
:::tip When does this matter?
Use the declarative manifest when you want reproducible skill setups across machines, team onboarding with a single command, or open-source project bootstrap.
@@ -12,11 +12,11 @@ Use the declarative manifest when you want reproducible skill setups across mach
## What Is a Skill Manifest?
-The `skills:` section in `config.yaml` serves as a **portable declaration** of your skill collection. Instead of manually installing skills one by one, you list them in config and run `skillshare install` to bring everything up.
+The `skills:` section in `registry.yaml` serves as a **portable declaration** of your skill collection. Instead of manually installing skills one by one, you list them in the registry and run `skillshare install` to bring everything up.
```yaml
-# ~/.config/skillshare/config.yaml (global)
-# or .skillshare/config.yaml (project)
+# ~/.config/skillshare/registry.yaml (global)
+# or .skillshare/registry.yaml (project)
skills:
- name: react-best-practices
source: anthropics/skills/skills/react-best-practices
@@ -29,6 +29,10 @@ skills:
source: anthropics/skills/skills/commit # no group → root level
```
+:::note Migration from config.yaml
+In older versions, `skills:` lived inside `config.yaml`. Skillshare automatically migrates it to `registry.yaml` on first load — no manual action required.
+:::
+
## How It Works
### Install from Manifest
@@ -36,10 +40,10 @@ skills:
Running `skillshare install` with **no arguments** reads the manifest and installs all listed skills:
```bash
-# Global mode — installs all skills from ~/.config/skillshare/config.yaml
+# Global mode — installs all skills from ~/.config/skillshare/registry.yaml
skillshare install
-# Project mode — installs from .skillshare/config.yaml
+# Project mode — installs from .skillshare/registry.yaml
skillshare install -p
# Preview without installing
@@ -52,14 +56,14 @@ Skills that already exist are skipped automatically.
The manifest stays in sync with your actual skill collection:
-- **`skillshare install `** — adds the installed skill to `skills:` automatically
-- **`skillshare uninstall ...`** — removes the entry from `skills:` automatically
+- **`skillshare install `** — adds the installed skill to `registry.yaml` automatically
+- **`skillshare uninstall ...`** — removes the entry from `registry.yaml` automatically
You never need to edit the manifest manually (though you can).
## Skill Entry Fields
-Each entry in the `skills:` list has these fields:
+Each entry in the `skills:` list in `registry.yaml` has these fields:
| Field | Required | Description |
|-------|----------|-------------|
@@ -75,11 +79,11 @@ Each entry in the `skills:` list has these fields:
Maintain your personal skill collection across machines:
```bash
-# On machine A — skills are already installed and tracked in config
-skillshare push # backup config to git
+# On machine A — skills are already installed and tracked in registry
+skillshare push # backup config + registry to git
# On machine B — fresh machine
-skillshare pull # restore config from git
+skillshare pull # restore config + registry from git
skillshare install # install all skills from manifest
skillshare sync # distribute to all targets
```
@@ -89,7 +93,7 @@ skillshare sync # distribute to all targets
New team members get the same AI context in one command:
```bash
-# .skillshare/config.yaml is committed to the repo
+# .skillshare/registry.yaml is committed to the repo
git clone
cd
skillshare install -p # installs all declared skills
@@ -101,7 +105,7 @@ skillshare sync -p # links to project targets
Project maintainers declare recommended skills:
```yaml
-# .skillshare/config.yaml
+# .skillshare/registry.yaml
skills:
- name: react-best-practices
source: anthropics/skills/skills/react-best-practices
@@ -117,7 +121,7 @@ When you install with `--into`, the group is recorded automatically:
```bash
skillshare install anthropics/skills/skills/pdf --into frontend
-# config.yaml will contain: name: pdf, group: frontend
+# registry.yaml will contain: name: pdf, group: frontend
```
Running `skillshare install` (no args) recreates the same directory structure from the manifest.
@@ -128,7 +132,7 @@ Contributors clone and run `skillshare install -p` to get project-specific AI co
## Workflow Summary
```
-1. Install skills normally → manifest auto-updates
+1. Install skills normally → registry.yaml auto-updates
2. Push/pull config via git → portable across machines
3. Run `skillshare install` → reproduce on new machine
4. Run `skillshare sync` → distribute to all targets
diff --git a/website/docs/understand/index.md b/website/docs/understand/index.md
index ded2ccfeb..a2461ee0a 100644
--- a/website/docs/understand/index.md
+++ b/website/docs/understand/index.md
@@ -24,7 +24,7 @@ flowchart LR
ORG_SRC["~/.config/skillshare/skills/"]
ORG_SRC -- sync --> ORG_T1["~/.claude/skills/"]
ORG_SRC -- sync --> ORG_T2["~/.cursor/skills/"]
- ORG_SRC -- sync --> ORG_T3["~/.opencode/"]
+ ORG_SRC -- sync --> ORG_T3["~/.config/opencode/skills/"]
ORG_T1 -. collect .-> ORG_SRC
end
@@ -57,6 +57,7 @@ flowchart LR
### Sync Modes
- **Merge** (default): Each skill symlinked individually, local skills preserved
+- **Copy**: Each skill copied individually, local skills preserved
- **Symlink**: Entire directory is one symlink
### Tracked Repos
diff --git a/website/docs/understand/philosophy/comparison.md b/website/docs/understand/philosophy/comparison.md
index f6820e315..1a4fa623b 100644
--- a/website/docs/understand/philosophy/comparison.md
+++ b/website/docs/understand/philosophy/comparison.md
@@ -31,8 +31,8 @@ skillshare uses a declarative model — you define your desired state once, then
source: ~/.config/skillshare/skills
targets:
claude: ~/.claude
- cursor: ~/.cursor/rules
- codex: ~/.codex
+ cursor: ~/.cursor/skills
+ codex: ~/.codex/skills
```
```bash
@@ -70,7 +70,7 @@ With skillshare, you configure targets once:
```yaml
targets:
claude: ~/.claude
- cursor: ~/.cursor/rules
+ cursor: ~/.cursor/skills
```
Then every `sync`, `install`, or `collect` knows where to go. No prompts.
@@ -84,7 +84,7 @@ skillshare's architecture prevents this entirely — the source directory is the
```
Source: ~/.config/skillshare/skills/my-skill/SKILL.md (always preserved)
├── ~/.claude/skills/my-skill → symlink to source ✓
- ├── ~/.cursor/rules/my-skill → symlink to source ✓ (unaffected)
+ ├── ~/.cursor/skills/my-skill → symlink to source ✓ (unaffected)
└── ~/.codex/skills/my-skill → symlink to source ✓ (unaffected)
```
diff --git a/website/docs/understand/project-skills.md b/website/docs/understand/project-skills.md
index e774667ee..e6fb814aa 100644
--- a/website/docs/understand/project-skills.md
+++ b/website/docs/understand/project-skills.md
@@ -20,7 +20,7 @@ Use project skills when your team needs repo-specific AI instructions (coding st
| **Project tooling** | CI/CD deployment knowledge, testing patterns, migration scripts specific to this repo |
| **Onboarding acceleration** | "How does auth work here?" — the AI already knows, from committed project skills |
| **Open source projects** | Maintainers commit `.skillshare/` so contributors get project-specific AI context on clone |
-| **Community skill curation** | A repo's `config.yaml` serves as a curated skill list — anyone can `install -p` to get the same setup |
+| **Community skill curation** | A repo's `registry.yaml` serves as a curated skill list — anyone can `install -p` to get the same setup |
---
@@ -85,7 +85,8 @@ skillshare sync -g # Force global mode
```
/
├── .skillshare/
-│ ├── config.yaml # Targets + remote skills list
+│ ├── config.yaml # Targets + settings
+│ ├── registry.yaml # Remote skills list (auto-managed)
│ ├── .gitignore # Ignores logs/ and cloned remote/tracked skill dirs
│ └── skills/
│ ├── my-local-skill/ # Created manually or via `skillshare new`
@@ -125,12 +126,21 @@ targets:
- cursor # Known target
- name: custom-ide # Custom target with explicit path
path: ./tools/ide/skills
- mode: symlink # Optional: "merge" (default) or "symlink"
+ mode: symlink # Optional: "merge" (default), "copy", or "symlink"
- name: codex # Optional filters (merge mode)
include: [codex-*]
exclude: [codex-experimental-*]
+```
-skills: # Remote skills (auto-managed by install/uninstall)
+**Targets** support two formats:
+- **Short**: Just the target name (e.g., `claude`). Uses known default path, merge mode.
+- **Long**: Object with `name`, optional `path`, optional `mode` (`merge`, `copy`, or `symlink`), and optional `include`/`exclude` filters. Supports relative paths (resolved from project root) and `~` expansion.
+
+Remote skill installations are tracked in a separate file, `.skillshare/registry.yaml`:
+
+```yaml
+# .skillshare/registry.yaml (auto-managed by install/uninstall)
+skills:
- name: pdf-skill
source: anthropic/skills/pdf
- name: _team-skills
@@ -138,16 +148,12 @@ skills: # Remote skills (auto-managed by install/unin
tracked: true # Tracked repo: cloned with git history
```
-**Targets** support two formats:
-- **Short**: Just the target name (e.g., `claude`). Uses known default path, merge mode.
-- **Long**: Object with `name`, optional `path`, optional `mode` (`merge` or `symlink`), and optional `include`/`exclude` filters. Supports relative paths (resolved from project root) and `~` expansion.
-
**Skills** list tracks remote installations only. Local skills don't need entries here.
- `tracked: true`: Installed with `--track` (git repo with `.git/` preserved). When someone runs `skillshare install -p`, tracked skills are cloned with full git history so `skillshare update` works correctly.
:::tip Portable Skill Manifest
-`config.yaml` is a portable skill manifest in both global and project mode. In a project, commit it to git and anyone can run `skillshare install -p && skillshare sync`. For global mode, copy `config.yaml` to a new machine and run `skillshare install && skillshare sync`. This works for teams, open source contributors, community templates, and dotfiles across machines.
+`config.yaml` and `registry.yaml` together form a portable skill manifest in both global and project mode. In a project, commit them to git and anyone can run `skillshare install -p && skillshare sync`. For global mode, copy both files to a new machine and run `skillshare install && skillshare sync`. This works for teams, open source contributors, community templates, and dotfiles across machines.
:::
---
diff --git a/website/docs/understand/skill-format.md b/website/docs/understand/skill-format.md
index 4b713fe07..1a35b0fc7 100644
--- a/website/docs/understand/skill-format.md
+++ b/website/docs/understand/skill-format.md
@@ -65,7 +65,7 @@ name: my-skill
**Rules:**
- Lowercase letters, numbers, hyphens, underscores
-- Must start with a letter or underscore
+- Must start with a letter or number
- Should be unique across all skills
**Examples:**
diff --git a/website/docs/understand/tracked-repositories.md b/website/docs/understand/tracked-repositories.md
index 622ac733c..b363e4f31 100644
--- a/website/docs/understand/tracked-repositories.md
+++ b/website/docs/understand/tracked-repositories.md
@@ -154,10 +154,10 @@ skillshare uninstall _team-skills
Tracked repos also work in project mode. The repo is cloned into `.skillshare/skills/` and added to `.skillshare/.gitignore` (so the tracked repo's git history doesn't conflict with your project's git). Project logs (`.skillshare/logs/`) are also ignored by default.
-Installing a tracked repo auto-records `tracked: true` in `.skillshare/config.yaml`, so new team members get the correct clone behavior via `skillshare install -p`:
+Installing a tracked repo auto-records `tracked: true` in `.skillshare/registry.yaml`, so new team members get the correct clone behavior via `skillshare install -p`:
```yaml
-# .skillshare/config.yaml (auto-updated after install --track -p)
+# .skillshare/registry.yaml (auto-updated after install --track -p)
skills:
- name: _team-shared-skills
source: github.com/team/shared-skills