From 1327586f307a06a3d662e751cf1c7733545536d6 Mon Sep 17 00:00:00 2001 From: Willie Date: Thu, 26 Feb 2026 09:02:20 +0800 Subject: [PATCH] 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 --- .../docs/how-to/advanced/docker-sandbox.md | 2 +- website/docs/how-to/advanced/migration.md | 6 ++- website/docs/how-to/advanced/security.md | 2 +- .../how-to/recipes/ci-cd-skill-validation.md | 2 +- .../recipes/cross-machine-sync-recipe.md | 2 +- .../recipes/private-enterprise-skills.md | 38 ++++++++++++------- website/docs/learn/with-devcontainer.md | 6 +-- website/docs/learn/with-multiple-tools.md | 9 ++--- .../appendix/environment-variables.md | 18 ++++++++- .../docs/reference/targets/configuration.md | 7 ++++ .../reference/targets/supported-targets.md | 19 +++++++--- .../docs/understand/declarative-manifest.md | 36 ++++++++++-------- website/docs/understand/index.md | 3 +- .../docs/understand/philosophy/comparison.md | 8 ++-- website/docs/understand/project-skills.md | 24 +++++++----- website/docs/understand/skill-format.md | 2 +- .../docs/understand/tracked-repositories.md | 4 +- 17 files changed, 120 insertions(+), 68 deletions(-) diff --git a/website/docs/how-to/advanced/docker-sandbox.md b/website/docs/how-to/advanced/docker-sandbox.md index 3dc23678a..5379843ca 100644 --- a/website/docs/how-to/advanced/docker-sandbox.md +++ b/website/docs/how-to/advanced/docker-sandbox.md @@ -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 diff --git a/website/docs/how-to/advanced/migration.md b/website/docs/how-to/advanced/migration.md index a67e24201..bc171abd9 100644 --- a/website/docs/how-to/advanced/migration.md +++ b/website/docs/how-to/advanced/migration.md @@ -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 diff --git a/website/docs/how-to/advanced/security.md b/website/docs/how-to/advanced/security.md index c896170b3..a8fcb6929 100644 --- a/website/docs/how-to/advanced/security.md +++ b/website/docs/how-to/advanced/security.md @@ -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 | diff --git a/website/docs/how-to/recipes/ci-cd-skill-validation.md b/website/docs/how-to/recipes/ci-cd-skill-validation.md index c81abb9f3..63aabee03 100644 --- a/website/docs/how-to/recipes/ci-cd-skill-validation.md +++ b/website/docs/how-to/recipes/ci-cd-skill-validation.md @@ -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 diff --git a/website/docs/how-to/recipes/cross-machine-sync-recipe.md b/website/docs/how-to/recipes/cross-machine-sync-recipe.md index 9b6d56ceb..3340c93df 100644 --- a/website/docs/how-to/recipes/cross-machine-sync-recipe.md +++ b/website/docs/how-to/recipes/cross-machine-sync-recipe.md @@ -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 diff --git a/website/docs/how-to/recipes/private-enterprise-skills.md b/website/docs/how-to/recipes/private-enterprise-skills.md index 0b3d17709..6e93b77e9 100644 --- a/website/docs/how-to/recipes/private-enterprise-skills.md +++ b/website/docs/how-to/recipes/private-enterprise-skills.md @@ -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 diff --git a/website/docs/learn/with-devcontainer.md b/website/docs/learn/with-devcontainer.md index 3f2531b5c..5930a10b3 100644 --- a/website/docs/learn/with-devcontainer.md +++ b/website/docs/learn/with-devcontainer.md @@ -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" } ``` diff --git a/website/docs/learn/with-multiple-tools.md b/website/docs/learn/with-multiple-tools.md index f4a36115c..7703d0681 100644 --- a/website/docs/learn/with-multiple-tools.md +++ b/website/docs/learn/with-multiple-tools.md @@ -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 diff --git a/website/docs/reference/appendix/environment-variables.md b/website/docs/reference/appendix/environment-variables.md index 2faebaca3..ffa144196 100644 --- a/website/docs/reference/appendix/environment-variables.md +++ b/website/docs/reference/appendix/environment-variables.md @@ -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 | diff --git a/website/docs/reference/targets/configuration.md b/website/docs/reference/targets/configuration.md index c628dd658..dd1913072 100644 --- a/website/docs/reference/targets/configuration.md +++ b/website/docs/reference/targets/configuration.md @@ -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. diff --git a/website/docs/reference/targets/supported-targets.md b/website/docs/reference/targets/supported-targets.md index a3abea39e..b9be08026 100644 --- a/website/docs/reference/targets/supported-targets.md +++ b/website/docs/reference/targets/supported-targets.md @@ -18,7 +18,7 @@ These are auto-detected during `skillshare init`:
AdaL - Agents + Universal Amp Antigravity Augment @@ -77,7 +77,7 @@ These are auto-detected during `skillshare init`: adal~/.adal/skills.adal/skills -agents~/.config/agents/skills.agents/skills +universal~/.config/agents/skills.agents/skills amp~/.config/agents/skills.agents/skills antigravity~/.gemini/antigravity/skills.agent/skills augment~/.augment/skills.augment/skills @@ -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