mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -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>~/.adal/skills</code></td><td><code>.adal/skills</code></td></tr>
|
||||
<tr id="target-agents"><td>agents</td><td><code>~/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-universal"><td>universal</td><td><code>~/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-amp"><td>amp</td><td><code>~/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-antigravity"><td>antigravity</td><td><code>~/.gemini/antigravity/skills</code></td><td><code>.agent/skills</code></td></tr>
|
||||
<tr id="target-augment"><td>augment</td><td><code>~/.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>~/.iflow/skills</code></td><td><code>.iflow/skills</code></td></tr>
|
||||
<tr id="target-junie"><td>junie</td><td><code>~/.junie/skills</code></td><td><code>.junie/skills</code></td></tr>
|
||||
<tr id="target-kilocode"><td>kilocode</td><td><code>~/.kilocode/skills</code></td><td><code>.kilocode/skills</code></td></tr>
|
||||
<tr id="target-kimi"><td>kimi</td><td><code>~/.kimi/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-kimi"><td>kimi</td><td><code>~/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-kiro"><td>kiro</td><td><code>~/.kiro/skills</code></td><td><code>.kiro/skills</code></td></tr>
|
||||
<tr id="target-kode"><td>kode</td><td><code>~/.kode/skills</code></td><td><code>.kode/skills</code></td></tr>
|
||||
<tr id="target-letta"><td>letta</td><td><code>~/.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>~/.pochi/skills</code></td><td><code>.pochi/skills</code></td></tr>
|
||||
<tr id="target-qoder"><td>qoder</td><td><code>~/.qoder/skills</code></td><td><code>.qoder/skills</code></td></tr>
|
||||
<tr id="target-qwen"><td>qwen</td><td><code>~/.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>~/.config/agents/skills</code></td><td><code>.agents/skills</code></td></tr>
|
||||
<tr id="target-roo"><td>roo</td><td><code>~/.roo/skills</code></td><td><code>.roo/skills</code></td></tr>
|
||||
<tr id="target-trae"><td>trae</td><td><code>~/.trae/skills</code></td><td><code>.trae/skills</code></td></tr>
|
||||
<tr id="target-trae-cn"><td>trae-cn</td><td><code>~/.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:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
```
|
||||
|
||||
|
||||
@@ -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.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user