mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
chore: release v0.19.12
This commit is contained in:
@@ -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 <source> -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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")
|
||||
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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": [
|
||||
{
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 <source>`** — adds the installed skill to `.metadata.json` automatically
|
||||
- **`skillshare uninstall <name>...`** — removes the entry from `.metadata.json` automatically
|
||||
- **`skillshare install <source>`** — adds the installed skill to the manifest automatically
|
||||
- **`skillshare uninstall <name>...`** — 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 <project-repo>
|
||||
cd <project-repo>
|
||||
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
|
||||
|
||||
@@ -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
|
||||
<project-root>/
|
||||
├── .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.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
@@ -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 <source> -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
|
||||
|
||||
Reference in New Issue
Block a user