docs: fix 17 factual errors across website documentation

Full content audit identified inaccuracies verified against source code:

Critical fixes:
- declarative-manifest: skills: migrated from config.yaml to registry.yaml
- private-enterprise-skills: fix token list, add --track, fix dir separator
- supported-targets: fix universal canonical name, kimi/replit paths, aliases
- with-multiple-tools: fix target list output format, opencode path

Moderate fixes:
- tracked-repositories, project-skills: update config examples for registry.yaml
- skill-format: name rule "underscore" -> "number" (per validSkillNameRegex)
- understand/index: fix opencode path in diagram, add copy mode
- comparison: ~/.cursor/rules -> ~/.cursor/skills
- configuration: fix backups path, add registry migration note
- with-devcontainer: add non-interactive flags for postCreateCommand
- migration: .source -> .skillshare-meta.json
- docker-sandbox: make --cmd -> ./scripts/test_docker.sh --cmd
- security: audit rule count 31 -> 32
- ci-cd-skill-validation: production -> CI docker image
- cross-machine-sync-recipe: replace unimplemented ignore with include/exclude
- environment-variables: add GH_TOKEN entry
This commit is contained in:
Willie
2026-02-26 22:27:23 +08:00
parent 631b3ef292
commit 1327586f30
17 changed files with 120 additions and 68 deletions
@@ -161,7 +161,7 @@ make playground-down
| New contributor onboarding | `make playground` — one command, ready to go | No more "install Go, set PATH, clone, build" setup guide |
| Automated skill quality gate in CI | `docker run ghcr.io/.../skillshare-ci audit /skills` | Previously required installing Go + building from source in every workflow |
| "Works on my machine" across contributors | Docker pins Go 1.25.5 + all dependencies | Different local Go versions causing test flakes |
| PR reviewer reproducing an issue | `make test-docker --cmd "go test -run TestXxx ..."` | Must clone + full local setup to reproduce |
| PR reviewer reproducing an issue | `./scripts/test_docker.sh --cmd "go test -run TestXxx ..."` | Must clone + full local setup to reproduce |
### Enterprise and self-hosted deployment
+4 -2
View File
@@ -67,8 +67,10 @@ skillshare collect --all
**Option B: Reinstall from source** (gets latest versions)
```bash
# Find original sources
cat ~/.claude/skills/pdf/.source # or similar
# Find original sources from skill metadata
cat ~/.config/skillshare/skills/pdf/.skillshare-meta.json
# or check the registry
cat ~/.config/skillshare/registry.yaml
# Reinstall
skillshare install anthropics/skills/skills/pdf
+1 -1
View File
@@ -32,7 +32,7 @@ No single layer catches everything. Combine manual review, automated scanning, c
| Layer | Tool | What it does |
|-------|------|-------------|
| **Review** | Manual | Read SKILL.md before installing — check for suspicious commands |
| **Audit** | `skillshare audit` | Automated pattern detection (31 built-in rules, 5 severity levels) |
| **Audit** | `skillshare audit` | Automated pattern detection (32 built-in rules, 5 severity levels) |
| **Custom Rules** | `audit-rules.yaml` | Organization-specific patterns (internal secrets, allowlists) |
| **CI/CD** | Pipeline gate | Block PRs that introduce risky skills |
@@ -54,7 +54,7 @@ Create `.gitlab-ci.yml`:
```yaml
skill-validation:
image: ghcr.io/runkids/skillshare:latest
image: ghcr.io/runkids/skillshare-ci:latest
stage: test
script:
- skillshare init
@@ -70,7 +70,7 @@ skillshare push
- **Auto-sync on login**: Add `skillshare pull && skillshare sync` to your shell profile (`.bashrc` / `.zshrc`)
- **Conflict resolution**: If two machines modify the same skill, `pull` uses git merge — resolve conflicts in the source directory
- **Selective sync**: Use the `ignore` field in `config.yaml` to exclude machine-specific skills from sync
- **Selective sync**: Use per-target `include` / `exclude` filters in `config.yaml` to control which skills sync to each machine
## Related
@@ -14,26 +14,36 @@ Your organization hosts internal skills in a private GitHub/GitLab repository. Y
### Step 1: Set up authentication
skillshare uses the same token resolution as `git`:
skillshare detects tokens from environment variables, with platform-specific vars taking priority over the generic fallback:
| Platform | Environment Variable |
|----------|---------------------|
| GitHub / GitHub Enterprise | `GITHUB_TOKEN` |
| GitLab / Self-hosted GitLab | `GITLAB_TOKEN` |
| Bitbucket | `BITBUCKET_TOKEN` (+ optional `BITBUCKET_USERNAME`) |
| Azure DevOps | `AZURE_DEVOPS_TOKEN` |
| Any platform (fallback) | `SKILLSHARE_GIT_TOKEN` |
```bash
# Option A: GitHub CLI (recommended)
gh auth login
# Option A: Git credential helper (recommended for GitHub)
gh auth login # sets up git credential helper for HTTPS
# Option B: Environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
# Option B: Platform-specific environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx # GitHub
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxx # GitLab
export AZURE_DEVOPS_TOKEN=your-pat-here # Azure DevOps
# Option C: For Azure DevOps
export AZURE_DEVOPS_TOKEN=your-pat-here
# Option C: Generic fallback (works with any HTTPS host)
export SKILLSHARE_GIT_TOKEN=your-token-here
```
### Step 2: Install from private repo
```bash
skillshare install your-org/internal-skills
skillshare install your-org/internal-skills --track
```
skillshare detects the token automatically from `gh auth token`, `GITHUB_TOKEN`, `GH_TOKEN`, or `AZURE_DEVOPS_TOKEN`.
skillshare detects the token automatically from the environment variables listed above.
### Step 3: Verify tracking
@@ -44,7 +54,7 @@ skillshare list
The installed repo appears with the `_` prefix (tracked repository):
```
_your-org__internal-skills/
_your-org-internal-skills/
├── code-review/
├── testing-standards/
└── deployment-checklist/
@@ -66,10 +76,10 @@ skillshare sync # Push to targets
## Variations
- **Selective install**: `skillshare install your-org/internal-skills --skill code-review` installs only one skill
- **CI/CD token**: In pipelines, use `GITHUB_TOKEN` from CI secrets
- **Self-hosted GitLab**: Use HTTPS URL directly: `skillshare install https://gitlab.internal.com/team/skills.git`
- **Gitee / AtomGit**: Supported via HTTPS URLs with token auth
- **Selective install**: `skillshare install your-org/internal-skills --track --skill code-review` installs only one skill
- **CI/CD token**: In pipelines, set the platform-specific env var (e.g., `GITHUB_TOKEN`) from CI secrets
- **Self-hosted GitLab**: Set `GITLAB_TOKEN` and use HTTPS URL: `skillshare install https://gitlab.internal.com/team/skills.git --track`
- **Gitee / AtomGit**: Supported via HTTPS URLs with `SKILLSHARE_GIT_TOKEN`
## Related
+3 -3
View File
@@ -22,14 +22,14 @@ Add two things to your `.devcontainer/devcontainer.json`:
```json
{
"postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init && skillshare sync"
"postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init --no-copy --all-targets --no-skill && skillshare sync"
}
```
That's it. When a team member opens the project in VS Code and clicks "Reopen in Container":
1. skillshare is installed automatically
2. `init` detects AI CLIs in the container and sets up targets
2. `init` runs non-interactively — adds all detected AI CLI targets, skips copy prompts and built-in skill installation
3. `sync` delivers skills to all targets
## Adding Project Skills
@@ -46,7 +46,7 @@ Then commit and update `postCreateCommand` to also sync project skills:
```json
{
"postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init && skillshare sync && skillshare sync -p"
"postCreateCommand": "curl -fsSL https://raw.githubusercontent.com/runkids/skillshare/main/install.sh | sh && skillshare init --no-copy --all-targets --no-skill && skillshare sync && skillshare sync -p"
}
```
+4 -5
View File
@@ -32,11 +32,10 @@ skillshare target list
Example output:
```
TARGET MODE PATH
claude merge ~/.claude/skills
cursor merge ~/.cursor/skills
codex merge ~/.codex/skills
opencode merge ~/.opencode/skills
claude ~/.claude/skills (merge)
cursor ~/.cursor/skills (merge)
codex ~/.codex/skills (merge)
opencode ~/.config/opencode/skills (merge)
```
## Step 3: Install Skills
@@ -95,7 +95,7 @@ Starting from v0.13.0, skillshare follows the XDG Base Directory Specification f
GitHub personal access token.
**Used for:**
- GitHub API requests (`skillshare search`, `skillshare upgrade`)
- GitHub API requests (`skillshare search`, `skillshare upgrade`, version check)
- **Git clone authentication** — automatically injected when installing private repos via HTTPS
**Creating a token:**
@@ -123,6 +123,21 @@ $env:GITHUB_TOKEN = "ghp_your_token"
---
### GH_TOKEN
Alternative GitHub token variable. Used by the [GitHub CLI (`gh`)](https://cli.github.com/) and recognized by skillshare as a fallback.
**Token resolution order:** `GITHUB_TOKEN` → `GH_TOKEN` → `gh auth token`
If you already use `gh` and have authenticated via `gh auth login`, skillshare picks up the token automatically — no extra env vars needed.
```bash
export GH_TOKEN=ghp_your_token_here
skillshare search "react patterns"
```
---
## Git Authentication
These variables enable HTTPS authentication for private repositories. When set, skillshare automatically injects the token during `install` and `update` — no URL modification needed.
@@ -288,6 +303,7 @@ export GITHUB_TOKEN="ghp_your_token_here"
| `XDG_STATE_HOME` | State directory (logs) | `~/.local/state` |
| `XDG_CACHE_HOME` | Cache directory (version check, UI) | `~/.cache` |
| `GITHUB_TOKEN` | GitHub API + git clone auth | None |
| `GH_TOKEN` | GitHub API (fallback for `GITHUB_TOKEN`) | None |
| `GITLAB_TOKEN` | GitLab git clone auth | None |
| `BITBUCKET_TOKEN` | Bitbucket git clone auth | None |
| `BITBUCKET_USERNAME` | Bitbucket username for app password auth | None |
@@ -11,10 +11,13 @@ Configuration file reference for skillshare.
```text
~/.config/skillshare/
├── config.yaml ← Configuration file
├── registry.yaml ← Skill registry (auto-managed)
├── skills/ ← Source directory (your skills)
│ ├── my-skill/
│ ├── another/
│ └── _team-repo/ ← Tracked repository
~/.local/share/skillshare/
└── backups/ ← Automatic backups
└── 2026-01-20.../
```
@@ -342,6 +345,10 @@ When you run `skillshare install` with no arguments, all listed skills that aren
The `skills:` list is automatically updated after each `install` and `uninstall` operation. You don't need to edit it manually.
:::note Migrated to registry.yaml
Starting from v0.16.2, installed skill entries are stored in a separate `registry.yaml` file instead of inside `config.yaml`. Existing `skills:` entries in `config.yaml` are migrated automatically on first run. The schema and fields remain the same.
:::
### `ignore`
Glob patterns for files to skip during sync.
@@ -18,7 +18,7 @@ These are auto-detected during `skillshare init`:
<div className="target-grid">
<a className="target-badge" href="#target-adal">AdaL</a>
<a className="target-badge" href="#target-agents">Agents</a>
<a className="target-badge" href="#target-universal">Universal</a>
<a className="target-badge" href="#target-amp">Amp</a>
<a className="target-badge" href="#target-antigravity">Antigravity</a>
<a className="target-badge" href="#target-augment">Augment</a>
@@ -77,7 +77,7 @@ These are auto-detected during `skillshare init`:
</thead>
<tbody>
<tr id="target-adal"><td>adal</td><td><code>&#126;/.adal/skills</code></td><td><code>.adal/skills</code></td></tr>
<tr id="target-agents"><td>agents</td><td><code>&#126;/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-universal"><td>universal</td><td><code>&#126;/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-amp"><td>amp</td><td><code>&#126;/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-antigravity"><td>antigravity</td><td><code>&#126;/.gemini/antigravity/skills</code></td><td><code>.agent/skills</code></td></tr>
<tr id="target-augment"><td>augment</td><td><code>&#126;/.augment/skills</code></td><td><code>.augment/skills</code></td></tr>
@@ -101,7 +101,7 @@ These are auto-detected during `skillshare init`:
<tr id="target-iflow"><td>iflow</td><td><code>&#126;/.iflow/skills</code></td><td><code>.iflow/skills</code></td></tr>
<tr id="target-junie"><td>junie</td><td><code>&#126;/.junie/skills</code></td><td><code>.junie/skills</code></td></tr>
<tr id="target-kilocode"><td>kilocode</td><td><code>&#126;/.kilocode/skills</code></td><td><code>.kilocode/skills</code></td></tr>
<tr id="target-kimi"><td>kimi</td><td><code>&#126;/.kimi/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-kimi"><td>kimi</td><td><code>&#126;/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-kiro"><td>kiro</td><td><code>&#126;/.kiro/skills</code></td><td><code>.kiro/skills</code></td></tr>
<tr id="target-kode"><td>kode</td><td><code>&#126;/.kode/skills</code></td><td><code>.kode/skills</code></td></tr>
<tr id="target-letta"><td>letta</td><td><code>&#126;/.letta/skills</code></td><td><code>.skills</code></td></tr>
@@ -115,7 +115,7 @@ These are auto-detected during `skillshare init`:
<tr id="target-pochi"><td>pochi</td><td><code>&#126;/.pochi/skills</code></td><td><code>.pochi/skills</code></td></tr>
<tr id="target-qoder"><td>qoder</td><td><code>&#126;/.qoder/skills</code></td><td><code>.qoder/skills</code></td></tr>
<tr id="target-qwen"><td>qwen</td><td><code>&#126;/.qwen/skills</code></td><td><code>.qwen/skills</code></td></tr>
<tr id="target-replit"><td>replit</td><td>—</td><td><code>.agents/skills</code></td></tr>
<tr id="target-replit"><td>replit</td><td><code>&#126;/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
<tr id="target-roo"><td>roo</td><td><code>&#126;/.roo/skills</code></td><td><code>.roo/skills</code></td></tr>
<tr id="target-trae"><td>trae</td><td><code>&#126;/.trae/skills</code></td><td><code>.trae/skills</code></td></tr>
<tr id="target-trae-cn"><td>trae-cn</td><td><code>&#126;/.trae-cn/skills</code></td><td><code>.trae/skills</code></td></tr>
@@ -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:
+20 -16
View File
@@ -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 <source>`** — adds the installed skill to `skills:` automatically
- **`skillshare uninstall <name>...`** — removes the entry from `skills:` automatically
- **`skillshare install <source>`** — adds the installed skill to `registry.yaml` automatically
- **`skillshare uninstall <name>...`** — 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 <project-repo>
cd <project-repo>
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
+2 -1
View File
@@ -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
@@ -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)
```
+15 -9
View File
@@ -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
```
<project-root>/
├── .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.
:::
---
+1 -1
View File
@@ -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:**
@@ -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