COPSPA-57 // Implement CLI tools for finding, installing and updating external skills (#4)

* COPSPA-57 // Implement CLI tools for finding, installing and updating external skills through the database currated at skills.sh

* COPSPA-57 // Update README with new functions and bump version

* COPSPA-57: Changelog

* Update CHANGELOG.md

---------

Co-authored-by: Patrick <p.mehringer@techdivision.com>
Co-authored-by: Patrick Mehringer <bullitt300@googlemail.com>

Author: MVogge

CHANGELOG.md

@@ -5,14 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.2.0] - 2025-03-04
+## [0.3.0] - 2026-03-12
+
+### Added
+- **skills.sh Integration**: New CLI tools for managing external skills from the skills.sh database
+  - `opencode-link external-skills:find [query]` - Search the skills.sh database for available skills
+  - `opencode-link external-skills:add <owner/repo> <skill-name>` - Add skill to config and install
+  - `opencode-link external-skills:install` - Install/update external skills
+  - `opencode-link external-skills:update` - Update external skills to latest version
+  - `opencode-link external-skills:list` - Show installed external skills
+- New modules:
+  - `lib/external-skills.js` - Core logic for external skills management
+  - `lib/skills-registry.js` - Skills registry management and search functionality
+- JSON schema generation for external skills validation
+
+### Changed
+- `bin/opencode-link.js` - Extended with new CLI commands for skills.sh integration
+- `README.md` - Updated documentation with new functions
+- `package.json` - Updated dependencies and version
+
+### Details
+This release introduces full integration with the skills.sh database, enabling users to discover, install, and manage custom skills. The implementation provides seamless interoperability with the OpenCode plugin system.
+
+## [0.2.0] - 2026-03-04
 
 ### Added
 - GitHub Actions workflow for automatic npm publishing on version tags
 - `files` array in package.json for explicit publish contents
 - npm provenance support for supply chain security
 
-## [0.1.0] - 2025-03-04
+## [0.1.0] - 2026-03-04
 
 ### Added
 - User config directory support (`~/.config/opencode/node_modules/`)

README.md

@@ -188,24 +188,115 @@ opencode-link time-tracking
 
 **Note:** Commands are prefixed with the plugin name to avoid conflicts between plugins.
 
+## External Skills
+
+External skills are agent skills sourced directly from GitHub repositories, curated via [skills.sh](https://skills.sh). They are downloaded and symlinked automatically — no npm install required.
+
+### Quick Start
+
+```bash
+# Search for skills
+opencode-link external-skills:find react
+
+# Add a skill to your project (updates opencode-project.json + installs immediately)
+opencode-link external-skills:add vercel-labs/agent-skills vercel-react-best-practices
+
+# Show installed external skills
+opencode-link external-skills:list
+```
+
+### How It Works
+
+1. Skills are configured in `.opencode/opencode-project.json` under `externalSkills`
+2. `opencode-link` (default run) detects the config and downloads/links them automatically
+3. Files land in `.opencode/.external-skills/<skill-name>/SKILL.md` (gitignored)
+4. Symlinks are created in `.opencode/skills/<skill-name>/`
+
+### Configuration (`opencode-project.json`)
+
+```json
+{
+  "externalSkills": [
+    {
+      "source": "vercel-labs/agent-skills",
+      "skills": ["vercel-react-best-practices", "vercel-nextjs-app-router"],
+      "branch": "main",
+      "category": "optional"
+    },
+    {
+      "source": "some-org/all-their-skills"
+    }
+  ]
+}
+```
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `source` | yes | — | GitHub `owner/repo` |
+| `skills` | no | all | Skill names to install. Omit to install all skills in the repo. |
+| `branch` | no | `main` | Git branch to download from |
+| `category` | no | `optional` | `standard` or `optional` |
+
+### Security Checks
+
+Before downloading, each skill is audited via three security partners (ATH, Socket, Snyk):
+
+| Risk level | Behaviour |
+|------------|-----------|
+| `safe` / `low` | Installed automatically |
+| `medium` | Installed with a warning |
+| `high` | Interactive confirmation required (non-interactive: aborted) |
+| `critical` | Always skipped |
+
+Use `--force` to bypass high-risk prompts or to force reinstall an up-to-date skill.
+
+> **Note:** Security data is fetched from `add-skill.vercel.sh`. If the service is unavailable, installation continues with a warning — it never blocks.
+
+### Update Detection
+
+Skills store a SHA fingerprint (`.skill-meta.json`) after download. Subsequent runs skip skills whose SHA hasn't changed. Use `external-skills:update` to explicitly pull the latest version.
+
+```bash
+# Re-download skills where the upstream SHA changed
+opencode-link external-skills:update
+
+# Force-reinstall all skills regardless of SHA
+opencode-link --force external-skills:install
+```
+
+### GitHub Rate Limits
+
+The GitHub API is used to fetch file SHAs. Set `GITHUB_TOKEN` to increase the rate limit:
+
+```bash
+export GITHUB_TOKEN=ghp_...
+opencode-link external-skills:install
+```
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `opencode-link` | Link all standard plugins |
+| `opencode-link` | Link all standard plugins + install configured external skills |
 | `opencode-link all` | Link ALL plugins (standard + optional) |
 | `opencode-link <plugin>` | Link a specific plugin |
-| `opencode-link list` | List available plugins |
+| `opencode-link list` | List available plugins and configured external skills |
 | `opencode-link status` | Show current links |
-| `opencode-link clean` | Remove all symlinks |
+| `opencode-link clean` | Remove all symlinks and `.external-skills/` directory |
 | `opencode-link schema` | Regenerate schema |
+| `opencode-link external-skills:find <query>` | Search skills.sh for skills |
+| `opencode-link external-skills:add <owner/repo> <skill>` | Add skill to config and install |
+| `opencode-link external-skills:install` | Install/update all configured external skills |
+| `opencode-link external-skills:update` | Re-download skills with upstream changes |
+| `opencode-link external-skills:list` | Show installed external skills with security status |
 
 ## Options
 
 | Flag | Description |
 |------|-------------|
 | `--target-dir=<path>` | Override target directory |
 | `--singular` | Use singular directory names (agent/ instead of agents/) |
+| `--force` | Force reinstall even if up to date; bypass high-risk security prompt |
 
 ## Programmatic Usage
 
@@ -215,14 +306,21 @@ You can also use the CLI modules programmatically:
 import { discoverPlugins, getContentTypes } from '@techdivision/opencode-cli/discovery';
 import { createSymlink, getItemsToLink } from '@techdivision/opencode-cli/linker';
 import { generateCombinedSchema } from '@techdivision/opencode-cli/schema';
+import { searchSkills, fetchAuditData } from '@techdivision/opencode-cli/skills-registry';
+import { installExternalSkills, listInstalledExternalSkills } from '@techdivision/opencode-cli/external-skills';
 
 // Discover plugins
 const plugins = discoverPlugins('/path/to/.opencode');
 console.log(`Found ${plugins.size} plugins`);
 
-// Get all content types
-const types = getContentTypes(plugins);
-console.log(`Content types: ${types.join(', ')}`);
+// Search skills.sh
+const results = await searchSkills('react');
+
+// Install configured external skills
+await installExternalSkills('/path/to/.opencode', { force: false });
+
+// List installed external skills
+const installed = listInstalledExternalSkills('/path/to/.opencode');
 ```
 
 ## License