diff --git a/CHANGELOG.md b/CHANGELOG.md index a7efafcf7..d0bffc0d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,24 @@ # Changelog +## [0.19.12] - 2026-05-14 + +### Bug Fixes + +- **Project `skills:` in config.yaml no longer stripped** — previously, project-mode commands silently removed the `skills:` section from `.skillshare/config.yaml` during an internal migration, leaving no committable record of remote skill dependencies. Now `skills:` stays in `config.yaml` as the declarative source of truth. Teammates can clone the repo and run `skillshare install -p` to install all listed skills. Refs: #157 + ```yaml + # .skillshare/config.yaml — committed to git + targets: + - claude + - cursor + skills: + - name: pdf + source: anthropic/skills/pdf + - name: review + source: github.com/team/skills/code-review + group: frontend + ``` + `skillshare install -p` automatically adds the skill to `config.yaml`. `skillshare uninstall` removes it. Runtime metadata (hashes, timestamps) stays in `.metadata.json` (gitignored) + ## [0.19.11] - 2026-05-14 ### New Features diff --git a/cmd/skillshare/install_context.go b/cmd/skillshare/install_context.go index 14947643e..e717385ac 100644 --- a/cmd/skillshare/install_context.go +++ b/cmd/skillshare/install_context.go @@ -66,7 +66,18 @@ type projectInstallContext struct { func (p *projectInstallContext) SourcePath() string { return p.runtime.sourcePath } func (p *projectInstallContext) ConfigSkills() []install.SkillEntryDTO { - return storeToSkillEntryDTOs(p.runtime.skillsStore) + skills := p.runtime.config.Skills + dtos := make([]install.SkillEntryDTO, 0, len(skills)) + for _, s := range skills { + dtos = append(dtos, install.SkillEntryDTO{ + Name: s.Name, + Source: s.Source, + Tracked: s.Tracked, + Group: s.Group, + Branch: s.Branch, + }) + } + return dtos } func (p *projectInstallContext) Reconcile() error { return reconcileProjectRemoteSkills(p.runtime) diff --git a/internal/config/project.go b/internal/config/project.go index de9d880b2..38c39c8be 100644 --- a/internal/config/project.go +++ b/internal/config/project.go @@ -256,6 +256,7 @@ func PruneStaleSkills(skills []SkillEntry, live map[string]bool, skillsOnly bool // ProjectConfig holds project-level config (.skillshare/config.yaml). type ProjectConfig struct { Targets []ProjectTargetEntry `yaml:"targets"` + Skills []SkillEntry `yaml:"skills,omitempty"` TargetNaming string `yaml:"target_naming,omitempty"` Extras []ExtraConfig `yaml:"extras,omitempty"` Audit AuditConfig `yaml:"audit,omitempty"` @@ -284,9 +285,6 @@ func ProjectConfigPath(projectRoot string) string { func LoadProject(projectRoot string) (*ProjectConfig, error) { path := ProjectConfigPath(projectRoot) - // Migrate skills[] to registry.yaml (one-time, silent) - _ = migrateProjectSkillsToRegistry(path, projectRoot) - data, err := os.ReadFile(path) if err != nil { if os.IsNotExist(err) { @@ -372,51 +370,6 @@ func (c *ProjectConfig) Save(projectRoot string) error { return nil } -// migrateProjectSkillsToRegistry extracts skills[] from project config.yaml into registry.yaml. -// Uses raw YAML parsing because ProjectConfig struct no longer has a Skills field. -func migrateProjectSkillsToRegistry(configPath, projectRoot string) error { - registryDir := filepath.Join(projectRoot, ".skillshare") - registryPath := RegistryPath(registryDir) - - if _, err := os.Stat(registryPath); err == nil { - return nil - } - - data, err := os.ReadFile(configPath) - if err != nil { - return nil - } - - var legacy struct { - Skills []SkillEntry `yaml:"skills,omitempty"` - } - if err := yaml.Unmarshal(data, &legacy); err != nil { - return nil - } - - if len(legacy.Skills) == 0 { - return nil - } - - reg := &Registry{Skills: legacy.Skills} - if err := reg.Save(registryDir); err != nil { - return fmt.Errorf("failed to create registry.yaml during project migration: %w", err) - } - - // Strip skills from project config.yaml - var raw map[string]any - if err := yaml.Unmarshal(data, &raw); err != nil { - return nil - } - delete(raw, "skills") - cleaned, err := marshalYAML(raw) - if err != nil { - return nil - } - cleaned = append(projectSchemaComment, cleaned...) - return os.WriteFile(configPath, cleaned, 0644) -} - // needsTargetMigration detects if a project config still uses legacy flat // target format by re-parsing targets and checking for flat fields. diff --git a/internal/config/project_reconcile.go b/internal/config/project_reconcile.go index 14062b01b..f3429ed1b 100644 --- a/internal/config/project_reconcile.go +++ b/internal/config/project_reconcile.go @@ -44,9 +44,78 @@ func ReconcileProjectSkills(projectRoot string, projectCfg *ProjectConfig, store } } + if projectCfg != nil && reconcileProjectConfigSkills(projectCfg, store, result.live) { + if err := projectCfg.Save(projectRoot); err != nil { + return fmt.Errorf("failed to save project config after reconcile: %w", err) + } + } + return nil } +// reconcileProjectConfigSkills syncs MetadataStore entries into ProjectConfig.Skills +// so the declarative skill list in config.yaml stays in sync with installed skills. +// Returns true if ProjectConfig.Skills was modified. +func reconcileProjectConfigSkills(cfg *ProjectConfig, store *install.MetadataStore, live map[string]bool) bool { + existing := make(map[string]int, len(cfg.Skills)) + for i, s := range cfg.Skills { + existing[s.FullName()] = i + } + + changed := false + + // Add entries present in store but missing from config. + for _, name := range store.List() { + entry := store.Get(name) + if entry == nil || entry.Source == "" { + continue + } + if entry.Kind == "agent" { + continue + } + if _, ok := existing[name]; ok { + continue + } + cfg.Skills = append(cfg.Skills, SkillEntry{ + Name: skillBaseName(name), + Source: entry.Source, + Tracked: entry.Tracked, + Group: entry.Group, + Branch: entry.Branch, + }) + changed = true + } + + // Remove config entries whose skills no longer exist on disk. + if len(live) > 0 || len(cfg.Skills) > 0 { + kept := cfg.Skills[:0] + for _, s := range cfg.Skills { + if live[s.FullName()] { + kept = append(kept, s) + } else if !storeHasSource(store, s.FullName()) { + changed = true + } else { + kept = append(kept, s) + } + } + cfg.Skills = kept + } + + return changed +} + +func skillBaseName(fullPath string) string { + if idx := strings.LastIndex(fullPath, "/"); idx >= 0 { + return fullPath[idx+1:] + } + return fullPath +} + +func storeHasSource(store *install.MetadataStore, name string) bool { + e := store.Get(name) + return e != nil && e.Source != "" +} + // ReconcileProjectAgents scans the project agents source directory for // installed agents and ensures they are present in the MetadataStore. // Also updates .skillshare/.gitignore for each agent. diff --git a/internal/config/project_reconcile_test.go b/internal/config/project_reconcile_test.go index 3779fe6d7..c94aa5021 100644 --- a/internal/config/project_reconcile_test.go +++ b/internal/config/project_reconcile_test.go @@ -161,6 +161,87 @@ func TestReconcileProjectSkills_NestedSkillSetsGroup(t *testing.T) { } } +// Issue #157: reconcile should add newly installed skill to ProjectConfig.Skills +func TestReconcileProjectSkills_AddsToConfigSkills(t *testing.T) { + root := t.TempDir() + skillsDir := filepath.Join(root, ".skillshare", "skills") + + skillPath := filepath.Join(skillsDir, "new-skill") + if err := os.MkdirAll(skillPath, 0755); err != nil { + t.Fatal(err) + } + + cfg := &ProjectConfig{ + Targets: []ProjectTargetEntry{{Name: "claude"}}, + } + // Write initial config.yaml + if err := cfg.Save(root); err != nil { + t.Fatal(err) + } + + store := install.NewMetadataStore() + store.Set("new-skill", &install.MetadataEntry{Source: "github.com/user/repo"}) + + if err := ReconcileProjectSkills(root, cfg, store, skillsDir); err != nil { + t.Fatalf("ReconcileProjectSkills failed: %v", err) + } + + if len(cfg.Skills) != 1 { + t.Fatalf("expected 1 config skill, got %d", len(cfg.Skills)) + } + if cfg.Skills[0].Name != "new-skill" { + t.Errorf("skill name = %q, want %q", cfg.Skills[0].Name, "new-skill") + } + if cfg.Skills[0].Source != "github.com/user/repo" { + t.Errorf("skill source = %q, want %q", cfg.Skills[0].Source, "github.com/user/repo") + } + + // Verify config.yaml on disk has the skill + loaded, err := LoadProject(root) + if err != nil { + t.Fatalf("LoadProject failed: %v", err) + } + if len(loaded.Skills) != 1 { + t.Fatalf("expected 1 skill in loaded config, got %d", len(loaded.Skills)) + } +} + +// Issue #157: reconcile should remove config skills for uninstalled skills +func TestReconcileProjectSkills_PrunesConfigSkills(t *testing.T) { + root := t.TempDir() + skillsDir := filepath.Join(root, ".skillshare", "skills") + + // Only "alive" exists on disk + if err := os.MkdirAll(filepath.Join(skillsDir, "alive"), 0755); err != nil { + t.Fatal(err) + } + + cfg := &ProjectConfig{ + Targets: []ProjectTargetEntry{{Name: "claude"}}, + Skills: []SkillEntry{ + {Name: "alive", Source: "github.com/user/alive"}, + {Name: "gone", Source: "github.com/user/gone"}, + }, + } + if err := cfg.Save(root); err != nil { + t.Fatal(err) + } + + store := install.NewMetadataStore() + store.Set("alive", &install.MetadataEntry{Source: "github.com/user/alive"}) + + if err := ReconcileProjectSkills(root, cfg, store, skillsDir); err != nil { + t.Fatalf("ReconcileProjectSkills failed: %v", err) + } + + if len(cfg.Skills) != 1 { + t.Fatalf("expected 1 config skill after prune, got %d", len(cfg.Skills)) + } + if cfg.Skills[0].Name != "alive" { + t.Errorf("remaining skill = %q, want %q", cfg.Skills[0].Name, "alive") + } +} + func TestReconcileProjectSkills_PrunesStaleEntries(t *testing.T) { root := t.TempDir() skillsDir := filepath.Join(root, ".skillshare", "skills") diff --git a/internal/config/project_test.go b/internal/config/project_test.go index 99eabca60..046a905f7 100644 --- a/internal/config/project_test.go +++ b/internal/config/project_test.go @@ -3,9 +3,96 @@ package config import ( "os" "path/filepath" + "strings" "testing" ) +// Issue #157: skills: section in config.yaml must survive LoadProject round-trip. +func TestLoadProject_PreservesSkills(t *testing.T) { + root := t.TempDir() + skillshareDir := filepath.Join(root, ".skillshare") + if err := os.MkdirAll(skillshareDir, 0755); err != nil { + t.Fatal(err) + } + + configYAML := `targets: + - claude +skills: + - name: pdf + source: anthropic/skills/pdf + - name: next-best-practices + source: vercel-labs/next-skills/next-best-practices + group: frontend +audit: + block_threshold: CRITICAL +` + configPath := filepath.Join(skillshareDir, "config.yaml") + os.WriteFile(configPath, []byte(configYAML), 0644) + + cfg, err := LoadProject(root) + if err != nil { + t.Fatalf("LoadProject failed: %v", err) + } + + if len(cfg.Skills) != 2 { + t.Fatalf("expected 2 skills, got %d", len(cfg.Skills)) + } + if cfg.Skills[0].Name != "pdf" { + t.Errorf("skills[0].Name = %q, want %q", cfg.Skills[0].Name, "pdf") + } + if cfg.Skills[0].Source != "anthropic/skills/pdf" { + t.Errorf("skills[0].Source = %q, want %q", cfg.Skills[0].Source, "anthropic/skills/pdf") + } + if cfg.Skills[1].Group != "frontend" { + t.Errorf("skills[1].Group = %q, want %q", cfg.Skills[1].Group, "frontend") + } + + // Verify config.yaml on disk still contains skills: section + data, err := os.ReadFile(configPath) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(data), "skills:") { + t.Error("config.yaml on disk should still contain 'skills:' after LoadProject") + } +} + +// Issue #157: skills survive Save → LoadProject round-trip. +func TestProjectConfig_SkillsRoundTrip(t *testing.T) { + root := t.TempDir() + skillshareDir := filepath.Join(root, ".skillshare") + if err := os.MkdirAll(skillshareDir, 0755); err != nil { + t.Fatal(err) + } + + cfg := &ProjectConfig{ + Targets: []ProjectTargetEntry{{Name: "claude"}}, + Skills: []SkillEntry{ + {Name: "pdf", Source: "anthropic/skills/pdf"}, + {Name: "my-tool", Source: "org/repo/my-tool", Tracked: true, Group: "tools"}, + }, + } + + if err := cfg.Save(root); err != nil { + t.Fatalf("Save failed: %v", err) + } + + loaded, err := LoadProject(root) + if err != nil { + t.Fatalf("LoadProject after Save failed: %v", err) + } + + if len(loaded.Skills) != 2 { + t.Fatalf("expected 2 skills after round-trip, got %d", len(loaded.Skills)) + } + if loaded.Skills[0].Name != "pdf" || loaded.Skills[0].Source != "anthropic/skills/pdf" { + t.Errorf("skills[0] mismatch: %+v", loaded.Skills[0]) + } + if loaded.Skills[1].Tracked != true || loaded.Skills[1].Group != "tools" { + t.Errorf("skills[1] mismatch: %+v", loaded.Skills[1]) + } +} + func TestLoadProject_ExtrasConfig(t *testing.T) { root := t.TempDir() skillshareDir := filepath.Join(root, ".skillshare") diff --git a/internal/config/registry_test.go b/internal/config/registry_test.go index ca8cbef6f..aeb8a04a3 100644 --- a/internal/config/registry_test.go +++ b/internal/config/registry_test.go @@ -279,7 +279,8 @@ func TestSourceRoot_GitAtParent(t *testing.T) { } } -func TestMigrateProjectSkillsToRegistry(t *testing.T) { +// Issue #157: LoadProject must preserve skills in config.yaml (no migration to registry). +func TestProjectSkillsNotMigratedToRegistry(t *testing.T) { root := t.TempDir() skillshareDir := filepath.Join(root, ".skillshare") if err := os.MkdirAll(skillshareDir, 0755); err != nil { @@ -287,25 +288,27 @@ func TestMigrateProjectSkillsToRegistry(t *testing.T) { } configPath := filepath.Join(skillshareDir, "config.yaml") - // Write old-format project config with skills oldConfig := "targets:\n - claude\nskills:\n - name: my-skill\n source: github.com/user/repo\n" if err := os.WriteFile(configPath, []byte(oldConfig), 0644); err != nil { t.Fatal(err) } - _, err := LoadProject(root) + cfg, err := LoadProject(root) if err != nil { t.Fatalf("LoadProject failed: %v", err) } - reg, err := LoadRegistry(skillshareDir) - if err != nil { - t.Fatalf("LoadRegistry failed: %v", err) + // Skills should be in ProjectConfig, not migrated to registry.yaml + if len(cfg.Skills) != 1 { + t.Fatalf("expected 1 skill in ProjectConfig, got %d", len(cfg.Skills)) } - if len(reg.Skills) != 1 { - t.Fatalf("expected 1 skill in registry, got %d", len(reg.Skills)) + if cfg.Skills[0].Name != "my-skill" { + t.Errorf("expected 'my-skill', got %q", cfg.Skills[0].Name) } - if reg.Skills[0].Name != "my-skill" { - t.Errorf("expected 'my-skill', got %q", reg.Skills[0].Name) + + // registry.yaml should NOT be created + registryPath := RegistryPath(skillshareDir) + if _, err := os.Stat(registryPath); err == nil { + t.Error("registry.yaml should not exist — skills stay in config.yaml") } } diff --git a/schemas/project-config.schema.json b/schemas/project-config.schema.json index 1ba9b684e..ef133b6df 100644 --- a/schemas/project-config.schema.json +++ b/schemas/project-config.schema.json @@ -29,6 +29,19 @@ ] ] }, + "skills": { + "type": "array", + "description": "Remote skills this project depends on. Committed with the project so teammates can run 'skillshare install -p' to install them all.", + "items": { + "$ref": "#/$defs/skillEntry" + }, + "examples": [ + [ + { "name": "pdf", "source": "anthropic/skills/pdf" }, + { "name": "next-best-practices", "source": "vercel-labs/next-skills/next-best-practices", "group": "frontend" } + ] + ] + }, "audit": { "$ref": "#/$defs/auditConfig" }, @@ -72,6 +85,38 @@ } }, "$defs": { + "skillEntry": { + "type": "object", + "description": "A remote skill dependency. Declares which skill to install and where it comes from.", + "required": ["name", "source"], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "description": "Skill name (the directory name under .skillshare/skills/).", + "examples": ["pdf", "next-best-practices"] + }, + "source": { + "type": "string", + "description": "Source path for installation (GitHub path, git URL, or local path).", + "examples": ["anthropic/skills/pdf", "vercel-labs/next-skills/next-best-practices"] + }, + "tracked": { + "type": "boolean", + "description": "True if installed with --track (preserves git history).", + "default": false + }, + "group": { + "type": "string", + "description": "Subdirectory group the skill belongs to (set by --into during install).", + "examples": ["frontend", "backend"] + }, + "branch": { + "type": "string", + "description": "Git branch to clone from. Omit for remote default branch." + } + } + }, "projectTargetEntry": { "oneOf": [ { diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md index 6a237aa11..8585aa9ee 100644 --- a/skills/skillshare/SKILL.md +++ b/skills/skillshare/SKILL.md @@ -15,7 +15,7 @@ description: | `.agentignore` and `enable`/`disable` for per-agent toggles. argument-hint: "[command] [target] [--json] [--dry-run] [-p|-g]" metadata: - version: v0.19.11 + version: v0.19.12 --- # Skillshare CLI diff --git a/tests/integration/install_project_test.go b/tests/integration/install_project_test.go index ac79f3404..c5a3bad94 100644 --- a/tests/integration/install_project_test.go +++ b/tests/integration/install_project_test.go @@ -101,6 +101,9 @@ func TestInstallProject_FromConfig_SkipsExisting(t *testing.T) { sb.WriteProjectConfig(projectRoot, `targets: - claude +skills: + - name: already-here + source: someone/skills/already-here `) // install (no args) → should skip existing diff --git a/website/docs/understand/declarative-manifest.md b/website/docs/understand/declarative-manifest.md index fd54c939b..bc849d44b 100644 --- a/website/docs/understand/declarative-manifest.md +++ b/website/docs/understand/declarative-manifest.md @@ -12,34 +12,41 @@ Use the declarative manifest when you want reproducible skill setups across mach ## What Is a Skill Manifest? -The `skills:` section in `.metadata.json` serves as a **portable declaration** of your skill collection. Instead of manually installing skills one by one, you list them in the metadata and run `skillshare install` to bring everything up. +A skill manifest is a **portable declaration** of your skill collection. Instead of manually installing skills one by one, you list them in a manifest file and run `skillshare install` to bring everything up. -```json -{ - "skills": [ - { - "name": "react-best-practices", - "source": "anthropics/skills/skills/react-best-practices", - "group": "frontend" - }, - { - "name": "_team-skills", - "source": "my-org/shared-skills", - "tracked": true, - "group": "devops" - }, - { - "name": "commit", - "source": "anthropics/skills/skills/commit" - } - ] -} +The manifest location depends on the mode: + +| Mode | Manifest location | Committable? | +|------|------------------|-------------| +| **Project** | `.skillshare/config.yaml` (`skills:` section) | Yes — commit to share with team | +| **Global** | `~/.config/skillshare/skills/.metadata.json` | No — personal machine state | + +### Project Mode Manifest + +In project mode, `skills:` lives in `config.yaml` alongside `targets:`: + +```yaml +# .skillshare/config.yaml +targets: + - claude + - cursor + +skills: + - name: react-best-practices + source: anthropics/skills/skills/react-best-practices + group: frontend + - name: _team-skills + source: my-org/shared-skills + tracked: true + - name: commit + source: anthropics/skills/skills/commit ``` -:::note Migration notes -- **From config.yaml**: In older versions, `skills:` lived inside `config.yaml`. Skillshare automatically migrates it to `.metadata.json` on first load. -- **From registry.yaml**: In v0.19+, skill records moved from `registry.yaml` to `.metadata.json` as the unified metadata store. The migration is automatic — no manual action required. -::: +This file is committed to git — teammates clone the repo and run `skillshare install -p` to install all listed skills. + +### Global Mode Manifest + +In global mode, skill records are stored in `.metadata.json` (the centralized metadata store). This file also contains runtime tracking data (hashes, timestamps) and is auto-managed. ## How It Works @@ -51,7 +58,7 @@ Running `skillshare install` with **no arguments** reads the manifest and instal # Global mode — installs all skills from ~/.config/skillshare/skills/.metadata.json skillshare install -# Project mode — installs from .skillshare/.metadata.json +# Project mode — installs all skills from .skillshare/config.yaml skills: section skillshare install -p # Preview without installing @@ -64,14 +71,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 `.metadata.json` automatically -- **`skillshare uninstall ...`** — removes the entry from `.metadata.json` automatically +- **`skillshare install `** — adds the installed skill to the manifest automatically +- **`skillshare uninstall ...`** — removes the entry from the manifest automatically -You never need to edit the manifest manually (though you can). +In project mode, `config.yaml` is updated. In global mode, `.metadata.json` is updated. You never need to edit the manifest manually (though you can). ## Skill Entry Fields -Each entry in the `skills:` list in `.metadata.json` has these fields: +Each entry in the `skills:` list has these fields: | Field | Required | Description | |-------|----------|-------------| @@ -101,7 +108,7 @@ skillshare sync # distribute to all targets New team members get the same AI context in one command: ```bash -# .skillshare/.metadata.json is committed to the repo +# .skillshare/config.yaml skills: section is committed to the repo git clone cd skillshare install -p # installs all declared skills @@ -110,30 +117,31 @@ skillshare sync -p # links to project targets ### Open-Source Bootstrap -Project maintainers declare recommended skills: +Project maintainers declare recommended skills in `config.yaml`: ```yaml -# .skillshare/.metadata.json -{ - "skills": +# .skillshare/config.yaml +targets: + - claude + - cursor + +skills: - name: react-best-practices source: anthropics/skills/skills/react-best-practices group: frontend - name: commit source: anthropics/skills/skills/commit - - name: project-conventions - source: ./skills/project-conventions ``` :::info Group field and `--into` When you install with `--into`, the group is recorded automatically: ```bash -skillshare install anthropics/skills/skills/pdf --into frontend -# .metadata.json will contain: name: pdf, group: frontend +skillshare install anthropics/skills/skills/pdf --into frontend -p +# config.yaml will contain: name: pdf, group: frontend ``` -Running `skillshare install` (no args) recreates the same directory structure from the manifest. +Running `skillshare install -p` (no args) recreates the same directory structure from the manifest. ::: Contributors clone and run `skillshare install -p` to get project-specific AI context immediately. @@ -141,6 +149,13 @@ Contributors clone and run `skillshare install -p` to get project-specific AI co ## Workflow Summary ``` +Project mode: +1. Install skills normally → config.yaml skills: auto-updates +2. Commit config.yaml via git → portable across team members +3. Run `skillshare install -p` → reproduce on clone +4. Run `skillshare sync` → distribute to all targets + +Global mode: 1. Install skills normally → .metadata.json auto-updates 2. Push/pull config via git → portable across machines 3. Run `skillshare install` → reproduce on new machine diff --git a/website/docs/understand/project-skills.md b/website/docs/understand/project-skills.md index ffcefec4e..7e67f5afd 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 `.metadata.json` serves as a curated skill list — anyone can `install -p` to get the same setup | +| **Community skill curation** | A repo's `config.yaml` `skills:` section serves as a curated skill list — anyone can `install -p` to get the same setup | --- @@ -86,7 +86,7 @@ skillshare sync -g # Force global mode / ├── .skillshare/ │ ├── config.yaml # Targets + settings (incl. extras) -│ ├── .metadata.json # Remote skills list (auto-managed) +│ ├── skills/.metadata.json # Runtime metadata (hashes, timestamps — auto-managed, gitignored) │ ├── .gitignore # Ignores logs/, trash/, backups/, and cloned remote/tracked skill dirs │ ├── extras/ # Extras source directories │ │ └── rules/ # e.g. extras init rules --target .claude/rules -p @@ -139,30 +139,33 @@ targets: - **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/.metadata.json`: +Remote skill dependencies are declared in `config.yaml` under `skills:`: -```json -{ - "skills": [ - { - "name": "pdf-skill", - "source": "anthropic/skills/pdf" - }, - { - "name": "_team-skills", - "source": "github.com/team/skills", - "tracked": true - } - ] -} +```yaml +targets: + - claude + - cursor + +skills: + - name: pdf + source: anthropic/skills/pdf + - name: _team-skills + source: github.com/team/skills + tracked: true + - name: review + source: github.com/team/skills/code-review + group: frontend ``` -**Skills** list tracks remote installations only. Local skills don't need entries here. +**Skills** list declares 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. +- `group`: Subdirectory path (corresponds to `--into` during install). + +Runtime metadata (install timestamps, file hashes, commit SHAs) is stored separately in `.skillshare/skills/.metadata.json` — this file is auto-managed and gitignored. :::tip Portable Skill Manifest -`config.yaml` and `.metadata.json` 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. +`config.yaml` is the declarative skill manifest. In a project, commit it to git and anyone can run `skillshare install -p && skillshare sync`. For global mode, `.metadata.json` serves as the manifest since global config doesn't need to be shared via git. ::: --- diff --git a/website/src/pages/changelog.md b/website/src/pages/changelog.md index 5b586bc99..f42bbbb60 100644 --- a/website/src/pages/changelog.md +++ b/website/src/pages/changelog.md @@ -9,6 +9,25 @@ All notable changes to skillshare are documented here. For the full commit histo --- +## [0.19.12] - 2026-05-14 + +### Bug Fixes + +- **Project `skills:` in config.yaml no longer stripped** — previously, project-mode commands silently removed the `skills:` section from `.skillshare/config.yaml` during an internal migration, leaving no committable record of remote skill dependencies. Now `skills:` stays in `config.yaml` as the declarative source of truth. Teammates can clone the repo and run `skillshare install -p` to install all listed skills. Refs: #157 + ```yaml + # .skillshare/config.yaml — committed to git + targets: + - claude + - cursor + skills: + - name: pdf + source: anthropic/skills/pdf + - name: review + source: github.com/team/skills/code-review + group: frontend + ``` + `skillshare install -p` automatically adds the skill to `config.yaml`. `skillshare uninstall` removes it. Runtime metadata (hashes, timestamps) stays in `.metadata.json` (gitignored) + ## [0.19.11] - 2026-05-14 ### New Features