Oussama Douhou oussamadouhou

Joined on 2025-03-08

@oussamadouhou/skill-system (0.1.5)

Published 2026-01-27 22:28:10 +00:00 by oussamadouhou

Set up this registry in your project .npmrc file:

@oussamadouhou:registry=

To install the package using npm, run the following command:

npm install @oussamadouhou/skill-system@0.1.5

or add it to the package.json file:

"@oussamadouhou/skill-system": "0.1.5"

For more information on the npm registry, see the documentation.

Skill System Plugin for OpenCode

Hybrid keyword + semantic skill matching system with proactive recommendations

Overview

The Skill System Plugin is an intelligent skill discovery and recommendation engine for OpenCode that combines:

🔍 Hybrid Matching: Keyword + semantic (embedding-based) matching with 85-90% success rate
⚡ Proactive Recommendations: Hook-based triggering suggests skills before you ask (84% success rate)
📂 Hierarchical Discovery: Auto-discovers skills from project, user, and global scopes
🎯 Context-Aware: File pattern and intent matching for precise recommendations
🚀 Performance: <50ms latency with caching and parallel loading

What Problem Does This Solve?

In large OpenCode setups with 40+ skills, agents struggle to:

Remember which skills exist
Choose the right skill for the task
Discover project-specific skills automatically

This plugin solves that by proactively recommending relevant skills based on your query, current file, and task context.

Features

✅ Core Capabilities

Feature	Description	Status
Keyword Matching	Fast token-based filtering (Stage 1)	✅
Semantic Matching	Embedding-based similarity (Stage 2, optional)	✅
Intent Patterns	Regex-based intent detection	✅
File Context	Skill activation based on current file	✅
Hook Injection	Proactive recommendations in command output	✅
Multi-Scope Discovery	Project → User → Global priority	✅
Lazy Loading	Deferred content loading for performance	✅
Caching	5-minute TTL with force refresh	✅

🎯 Matching Strategies

Keyword Matching (30% weight)
- Exact keyword matches in skill metadata
- Tag matching
- Description token matching
Semantic Matching (50% weight, optional)
- Uses all-MiniLM-L6-v2 embeddings (384 dimensions)
- Cosine similarity scoring
- Fallback to keywords if embeddings unavailable
Intent Patterns (15% weight)
- Regex pattern matching
- Captures complex queries like "create a migration for users table"
File Context (5% weight)
- Auto-activates skills based on current file extension
- Example: *.md → wiki-manager skill

Remote Skill Search

The Skill System Plugin now supports searching and installing skills from community marketplaces:

SkillsMP (6,034+ skills)
SkillHub (16,100 skills with S-Rank ratings)
GitHub (25,000+ skills from awesome-claude-skills)

Configuration

{
  "plugins": [
    {
      "name": "skill-system",
      "config": {
        "remoteSearch": {
          "enabled": true,
          "sources": ["skillsmp", "skillhub", "github"],
          "apiKeys": {
            "skillsmp": "sk_live_...",
            "github": "gho_..."
          }
        }
      }
    }
  ]
}

Usage Examples

Search Local + Remote

const registry = new UnifiedSkillRegistry(projectDir, config)
const result = await registry.searchAll({ query: "git workflow" })

Install Remote Skill

await registry.installSkill(remoteSkill, 'user')

API Reference

See full API documentation in API.md.

registry.searchAll(options): Search combined local and remote sources
registry.searchRemote(options): Search only remote marketplaces
registry.installSkill(skill, scope): Install a remote skill to local, user, or global scope

GitHub Token Setup

To search GitHub repositories, you need a personal access token (classic):

Go to GitHub Developer Settings > Personal access tokens > Tokens (classic)
Generate new token with public_repo scope
Add the token to apiKeys.github in your configuration

Installation

Prerequisites

OpenCode 1.0+
Bun 1.0+ or Node.js 18+
TypeScript 5.9+

Option 1: Manual Installation

# Clone or copy this directory to OpenCode plugins
cd ~/.config/opencode/plugins/
git clone <repository-url> skill-system

# Install dependencies
cd skill-system
bun install

# Build
bun run build

Option 2: NPM Package (Coming Soon)

bun add @oussamadouhou/skill-system

Enable Plugin

Add to your OpenCode config (~/.config/opencode/config.json):

{
  "plugins": [
    {
      "name": "skill-system",
      "path": "~/.config/opencode/plugins/skill-system/dist/plugin-entry.js",
      "enabled": true
    }
  ]
}

GitHub Token Setup (Optional but Recommended)

To enable authenticated GitHub API requests with higher rate limits:

Rate Limits:

Unauthenticated: 10 requests/minute
Authenticated: 5000 requests/hour

Setup:

Get your GitHub token:
```
gh auth token
```
Set environment variable:
```
export GITHUB_TOKEN=$(gh auth token)
```
Add to your shell profile (.bashrc, .zshrc, etc.):
```
export GITHUB_TOKEN=$(gh auth token)
```
Verify it works:
```
echo $GITHUB_TOKEN
```

Testing:

Run the test script to verify your token setup:

export GITHUB_TOKEN=$(gh auth token)
bun run test-github-with-token.ts

Expected output:

✅ Token found
✅ Found 10+ skills from GitHub
✅ Rate limit information displayed

Quick Start

1. Discover Skills

The plugin automatically discovers skills from:

.opencode/skills/ (project-specific)
~/.config/opencode/skills/ (user-specific)
System-wide global directories

2. Query Skills

import { createSkillSystem } from "@oussamadouhou/skill-system"

const system = createSkillSystem(pluginContext)

// Find skills for a query
const result = await system.filterSkills("create database migration")

// Show recommendations
result.matches.forEach(match => {
  console.log(`${match.skill.name}: ${(match.confidence * 100).toFixed(0)}%`)
})

3. Automatic Recommendations

When enabled, the plugin injects recommendations automatically:

User: create a migration for users table

💡 SKILL RECOMMENDATION:
- migration-generator (92% match) - Generate database migrations
- drizzle-postgres-schema (78% match) - PostgreSQL schema generation

Configuration

Full Configuration Example

{
  "plugins": [
    {
      "name": "skill-system",
      "path": "~/.config/opencode/plugins/skill-system/dist/plugin-entry.js",
      "config": {
        "enabled": true,
        "contextBudget": 15000,
        "defaultConfidenceThreshold": 0.75,
        "maxSuggestions": 3,
        "verboseLogging": false,
        "cacheTtlMs": 300000,
        "parallelLoading": true,
        "embedding": {
          "enabled": true,
          "provider": "local",
          "model": "Xenova/all-MiniLM-L6-v2"
        },
        "hookInjection": {
          "enabled": true,
          "forceEvaluation": true,
          "prefix": "💡 SKILL RECOMMENDATION:"
        }
      }
    }
  ]
}

Configuration Options

Option	Type	Default	Description
`enabled`	boolean	`true`	Enable/disable plugin
`contextBudget`	number	`15000`	Max chars for skill descriptions
`defaultConfidenceThreshold`	number	`0.75`	Minimum confidence to match (0.0-1.0)
`maxSuggestions`	number	`3`	Max suggestions to show
`verboseLogging`	boolean	`false`	Enable debug logs
`cacheTtlMs`	number	`300000`	Cache lifetime (5 minutes)
`parallelLoading`	boolean	`true`	Parallel skill discovery
`embedding.enabled`	boolean	`true`	Enable semantic matching
`embedding.provider`	string	`"local"`	`"local"` or `"remote"`
`embedding.model`	string	`"Xenova/all-MiniLM-L6-v2"`	Model name
`hookInjection.enabled`	boolean	`true`	Proactive recommendations
`hookInjection.prefix`	string	`"SKILL ACTIVATION CHECK:"`	Recommendation prefix

Creating Skills

Skill File Format

Skills are Markdown files with YAML frontmatter:

---
name: my-awesome-skill
description: Does amazing things. Triggers 'amazing', 'awesome', 'fantastic'
category: development
keywords:
  - amazing
  - awesome
  - fantastic
intentPatterns:
  - "create.*amazing"
  - "build.*fantastic.*thing"
filePatterns:
  - "**/*.ts"
  - "**/*.js"
tags:
  - automation
  - productivity
compatibility: opencode
version: 1.0.0
---

# My Awesome Skill

## What This Skill Does

[Detailed instructions for the LLM...]

## When to Use

- When building amazing things
- When you need fantastic results

## Examples

```typescript
// Example code here


### Metadata Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | ✅ | Unique skill identifier |
| `description` | ✅ | Short description with trigger phrases |
| `category` | ⬜ | Category (development/devops/testing/etc.) |
| `keywords` | ⬜ | Keywords for matching |
| `intentPatterns` | ⬜ | Regex patterns for intent matching |
| `filePatterns` | ⬜ | File globs for context-aware activation |
| `tags` | ⬜ | Cross-cutting tags |
| `compatibility` | ⬜ | Required platform/version |
| `version` | ⬜ | Skill version |

---

## API Reference

See [API.md](./docs/API.md) for complete API documentation.

### Quick Reference

```typescript
// Create skill system
const system = createSkillSystem(pluginContext)

// Get all skills
const skills = await system.getSkills()

// Filter skills
const result = await system.filterSkills(query, currentFile, agent)

// Get specific skill
const skill = await system.getSkillByName("git-master")

// Refresh cache
await system.refreshSkills()

// Listen to events
system.addEventListener((event) => {
  console.log(event.type, event)
})

Performance

Benchmarks

Operation	Time	Notes
Initial discovery (50 skills)	~100ms	First run
Cached discovery	<5ms	Subsequent calls
Keyword filtering	~10ms	50 skills
Hybrid filtering	~15ms	With embeddings
Embedding computation	~50ms	Per skill (cached)

Optimization Tips

Enable caching (default 5min TTL)
Use parallel loading (enabled by default)
Lazy content loading (only when needed)
Pre-compute embeddings (stored in memory)

Testing

# Run all tests
bun test

# Run with coverage
bun test --coverage

# Watch mode
bun test --watch

Test Suite: ✅ 26/26 tests passing

Troubleshooting

Skills Not Found

Check skill directories exist:

ls -la ~/.config/opencode/skills/
ls -la .opencode/skills/

Enable verbose logging:
```
{ "verboseLogging": true }
```
Force refresh:
```
await system.refreshSkills()
```

Low Match Scores

Add more keywords to skill frontmatter
Lower defaultConfidenceThreshold (e.g., 0.65)
Add intentPatterns for complex queries

Embedding Issues

The system automatically falls back to keyword matching if embeddings fail.

To disable embeddings:

{
  "embedding": { "enabled": false }
}

Development

Setup

git clone <repo-url>
cd skill-system
bun install
bun run build

Scripts

bun run build      # Build TypeScript
bun run typecheck  # Type check only
bun test           # Run tests
bun run clean      # Remove dist/

Project Structure

skill-system/
├── src/
│   ├── plugin.ts              # Main plugin logic
│   ├── plugin-entry.ts        # Entry point
│   ├── types.ts               # TypeScript types
│   ├── skill-loader.ts        # Discovery logic
│   ├── skill-filter.ts        # Matching algorithms
│   ├── skill-filter.test.ts   # Tests
│   └── embedding/             # Embedding services
├── dist/                      # Built output
├── package.json
├── tsconfig.json
└── README.md

Research Background

This plugin implements research-validated patterns:

Hybrid Matching: 85-90% success rate
Proactive Triggering: 84% success rate
Hierarchical Organization: Reduces cognitive load

See:

Roadmap

v0.2.0 - Remote embedding API support
v0.3.0 - Usage analytics & feedback loop
v0.4.0 - Multi-language skills
v0.5.0 - Visual skill browser
v1.0.0 - Production release

License

MIT - See LICENSE

Author

Oussama Douhou

Research-driven OpenCode plugin development
Based on real-world skill system analysis (Jan 2026)

Built with ❤️ for OpenCode

Dependencies

ID	Version
@oussamadouhou/skill-system	^0.1.2
@xenova/transformers	^2.17.2

Development Dependencies

ID	Version
@opencode-ai/plugin	^1.1.35
@types/node	^22.13.0
opencode-rules	^0.3.0
typescript	^5.9.3

Peer Dependencies

ID	Version
@opencode-ai/plugin	>=1.1.0

opencode plugin skill ai llm semantic matching hybrid embeddings skill-discovery recommendations context-aware

Details

npm

2026-01-27 22:28:10 +00:00

Oussama Douhou

Project Site

MIT

97 KiB

Assets (1)

skill-system-0.1.5.tgz 97 KiB

Versions (11) View all

0.1.10

2026-01-27

0.1.9

2026-01-27

0.1.8

2026-01-27

0.1.7

2026-01-27

0.1.6

2026-01-27

@oussamadouhou/skill-system (0.1.5)

Installation

About this package

Skill System Plugin for OpenCode

Overview

What Problem Does This Solve?

Features

✅ Core Capabilities

🎯 Matching Strategies

Remote Skill Search

Configuration

Usage Examples

Search Local + Remote

Install Remote Skill

API Reference

GitHub Token Setup

Installation

Prerequisites

Option 1: Manual Installation

Option 2: NPM Package (Coming Soon)

Enable Plugin

GitHub Token Setup (Optional but Recommended)

Quick Start

1. Discover Skills

2. Query Skills

3. Automatic Recommendations

Configuration

Full Configuration Example

Configuration Options

Creating Skills

Skill File Format

Performance

Benchmarks

Optimization Tips

Testing

Troubleshooting

Skills Not Found

Low Match Scores

Embedding Issues

Development

Setup

Scripts

Project Structure

Research Background

Roadmap

License

Author

Dependencies

Keywords