opencode-skills-collection 2.0.300 → 3.0.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="./docs/logo.svg" alt="OpenCode Skills Collection"/>
+<img src="docs/assets/logo.svg" alt="OpenCode Skills Collection"/>
 
 <br/>
 <br/>
@@ -36,8 +36,7 @@ The plugin operates in two phases:
 
 **1. Local deployment (startup)**
 
-When OpenCode starts, the plugin copies the pre-bundled skills from the npm package and runs the **SkillPointer pipeline
-**:
+When OpenCode starts, the plugin copies the pre-bundled skills from the npm package and runs the SkillPointer pipeline:
 
 ```
 bundled-skills/ (npm package)
@@ -88,7 +87,7 @@ After the first startup, your `~/.config/opencode/` directory looks like this:
 
 |                      | Without SkillPointer | With SkillPointer   |
 |----------------------|----------------------|---------------------|
-| Folders in `skills/` | ~1000                 | ~35                 |
+| Folders in `skills/` | ~1000                | ~35                 |
 | Tokens at startup    | ~80,000              | ~255                |
 | Skills available     | All injected upfront | On-demand via vault |
 | Compaction loops     | ✗ frequent           | ✓ none              |
@@ -140,6 +139,39 @@ opencode run /refactor clean up this function
 
 ---
 
+## Skill Risk Filter
+
+The plugin supports configurable risk-based filtering of skills. By default, **all skills are loaded** — filtering is
+opt-in.
+
+Each skill in the index has a `risk` field with one of these levels:
+
+| Level       | Description                                                        |
+|-------------|--------------------------------------------------------------------|
+| `none`      | No risk assessment                                                 |
+| `safe`      | Verified safe                                                      |
+| `critical`  | Contains sensitive operations                                      |
+| `offensive` | Contains offensive security tools (exploits, reverse shells, etc.) |
+| `unknown`   | Not yet classified                                                 |
+
+### Configuration
+
+Create a `~/.config/opencode/skill-filter.jsonc` file:
+
+```jsonc
+{
+  "excludedRiskLevels": ["offensive"],
+  "excludedSkills": ["windows-privilege-escalation"]
+}
+```
+
+- **`excludedRiskLevels`**: Array of risk levels to block entirely
+- **`excludedSkills`**: Array of specific skill IDs to block
+
+Blocked skills are excluded from both the vault and the generated pointers — they are never loaded into context.
+
+---
+
 ## Development
 
 **Requirements:** Node.js ≥ 20, TypeScript ≥ 5

package/dist/skill-pointer/config-loader.d.ts

@@ -0,0 +1,11 @@
+import type { RiskLevel } from "./risk-level.js";
+export interface SkillRiskFilterConfig {
+    excludedRiskLevels?: RiskLevel[];
+    excludedSkills?: string[];
+}
+export declare const DEFAULT_FILTER_CONFIG_PATH: string;
+/**
+ * Loads filter config from skill-filter.jsonc. Missing file or section returns defaults.
+ * @param configPath Optional override (for testing).
+ */
+export declare function loadFilterConfig(configPath?: string): SkillRiskFilterConfig;

package/dist/skill-pointer/config-loader.js

@@ -0,0 +1,36 @@
+import os from "os";
+import path from "path";
+import fs from "fs";
+import stripJsonComments from "strip-json-comments";
+const DEFAULT_CONFIG = {
+    excludedRiskLevels: [],
+    excludedSkills: [],
+};
+export const DEFAULT_FILTER_CONFIG_PATH = path.join(os.homedir(), ".config", "opencode", "skill-filter.jsonc");
+const VALID_RISK_LEVELS = ["none", "safe", "critical", "offensive", "unknown"];
+/**
+ * Loads filter config from skill-filter.jsonc. Missing file or section returns defaults.
+ * @param configPath Optional override (for testing).
+ */
+export function loadFilterConfig(configPath) {
+    const resolvedPath = configPath ?? DEFAULT_FILTER_CONFIG_PATH;
+    if (!fs.existsSync(resolvedPath)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    try {
+        const raw = fs.readFileSync(resolvedPath, "utf-8");
+        const stripped = stripJsonComments(raw);
+        const parsed = JSON.parse(stripped);
+        return {
+            excludedRiskLevels: Array.isArray(parsed.excludedRiskLevels)
+                ? parsed.excludedRiskLevels.filter((v) => VALID_RISK_LEVELS.includes(v))
+                : DEFAULT_CONFIG.excludedRiskLevels,
+            excludedSkills: Array.isArray(parsed.excludedSkills)
+                ? parsed.excludedSkills
+                : DEFAULT_CONFIG.excludedSkills,
+        };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}

package/dist/skill-pointer/index.d.ts

@@ -8,6 +8,10 @@ export interface SkillPointerOptions {
      * Defaults to ~/.config/opencode/skill-libraries
      */
     vaultDir?: string;
+    /**
+     * Optional path to the risk filter configuration file.
+     */
+    configPath?: string;
 }
 /**
  * Orchestrates the full SkillPointer pipeline:

package/dist/skill-pointer/index.js

@@ -4,6 +4,8 @@ import { VAULT_DIR_NAME } from "../constants/constants.js";
 import { ensureDir } from "../utils/fs.utils.js";
 import { generatePointers } from "./pointer-generator.js";
 import { installSkillsToVault, loadSkillsIndex } from "./vault-installer.js";
+import { filterIndex } from "./skill-risk-filter.js";
+import { loadFilterConfig, DEFAULT_FILTER_CONFIG_PATH } from "./config-loader.js";
 function resolveDefaultVaultDir() {
     return path.join(os.homedir(), ".config", "opencode", VAULT_DIR_NAME);
 }
@@ -23,6 +25,9 @@ export function runSkillPointer(options) {
     ensureDir(options.activeSkillsDir);
     ensureDir(vaultDir);
     const index = loadSkillsIndex(options.bundledSkillsPath);
-    installSkillsToVault(options.bundledSkillsPath, vaultDir, index);
-    generatePointers(options.activeSkillsDir, vaultDir, index);
+    const configPath = options.configPath ?? DEFAULT_FILTER_CONFIG_PATH;
+    const config = loadFilterConfig(configPath);
+    const filteredIndex = filterIndex(index, config);
+    installSkillsToVault(options.bundledSkillsPath, vaultDir, filteredIndex);
+    generatePointers(options.activeSkillsDir, vaultDir, filteredIndex);
 }

package/dist/skill-pointer/pointer-generator.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { POINTER_SUFFIX, SKILL_FILENAME, UNCATEGORIZED_CATEGORY } from "../constants/constants.js";
-import { ensureDir, listSubdirectories } from "../utils/fs.utils.js";
+import { ensureDir } from "../utils/fs.utils.js";
 function buildPointerContent(category, skills, libraryPath) {
     const title = category
         .replace(/-/g, " ")
@@ -14,7 +14,7 @@ function buildPointerContent(category, skills, libraryPath) {
     return `---
 name: ${category}${POINTER_SUFFIX}
 description: "Pointer to a library of ${skillCount} specialized ${title} skills. Use when working on ${category}-related tasks."
-risk: safe
+risk: none
 ---
 
 # ${title} Capability Library 🎯
@@ -46,7 +46,6 @@ ${skillList}
  * via get_available_skills without loading every SKILL.md.
  */
 export function generatePointers(activeSkillsDir, vaultDir, index = []) {
-    const categoryDirs = listSubdirectories(vaultDir);
     const byCategory = new Map();
     for (const entry of index) {
         const cat = entry.category ?? UNCATEGORIZED_CATEGORY;
@@ -54,20 +53,18 @@ export function generatePointers(activeSkillsDir, vaultDir, index = []) {
             byCategory.set(cat, []);
         byCategory.get(cat).push(entry);
     }
-    for (const categoryName of categoryDirs) {
-        const categoryVaultPath = path.join(vaultDir, categoryName);
-        let skills = byCategory.get(categoryName) ?? [];
-        if (skills.length === 0) {
-            const subDirs = fs.readdirSync(categoryVaultPath).filter((e) => fs.statSync(path.join(categoryVaultPath, e)).isDirectory());
-            if (subDirs.length === 0)
+    const expectedPointers = new Set([...byCategory.keys()].map((c) => `${c}${POINTER_SUFFIX}`));
+    if (fs.existsSync(activeSkillsDir)) {
+        for (const dirent of fs.readdirSync(activeSkillsDir, { withFileTypes: true })) {
+            if (!dirent.isDirectory() || !dirent.name.endsWith(POINTER_SUFFIX))
                 continue;
-            skills = subDirs.map((dir) => ({
-                id: dir,
-                category: categoryName,
-                name: dir.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
-                description: dir.replace(/-/g, " "),
-            }));
+            if (!expectedPointers.has(dirent.name)) {
+                fs.rmSync(path.join(activeSkillsDir, dirent.name), { recursive: true, force: true });
+            }
         }
+    }
+    for (const [categoryName, skills] of byCategory.entries()) {
+        const categoryVaultPath = path.join(vaultDir, categoryName);
         const pointerDir = path.join(activeSkillsDir, `${categoryName}${POINTER_SUFFIX}`);
         ensureDir(pointerDir);
         fs.writeFileSync(path.join(pointerDir, SKILL_FILENAME), buildPointerContent(categoryName, skills, categoryVaultPath), "utf-8");

package/dist/skill-pointer/risk-level.d.ts

@@ -0,0 +1 @@
+export type RiskLevel = "none" | "safe" | "critical" | "offensive" | "unknown";

package/dist/skill-pointer/risk-level.js

@@ -0,0 +1 @@
+export {};

package/dist/skill-pointer/skill-risk-filter.d.ts

@@ -0,0 +1,5 @@
+import type { RiskLevel } from "./risk-level.js";
+import type { SkillIndexEntry } from "./vault-installer.js";
+import type { SkillRiskFilterConfig } from "./config-loader.js";
+export declare function shouldLoad(skillId: string, risk: RiskLevel | undefined, config: SkillRiskFilterConfig): boolean;
+export declare function filterIndex(index: SkillIndexEntry[], config: SkillRiskFilterConfig): SkillIndexEntry[];

package/dist/skill-pointer/skill-risk-filter.js

@@ -0,0 +1,15 @@
+export function shouldLoad(skillId, risk, config) {
+    const effectiveRisk = risk ?? "unknown";
+    if ((config.excludedRiskLevels ?? []).includes(effectiveRisk)) {
+        return false;
+    }
+    if ((config.excludedSkills ?? []).includes(skillId)) {
+        return false;
+    }
+    return true;
+}
+export function filterIndex(index, config) {
+    return index.filter((entry) => {
+        return shouldLoad(entry.id, entry.risk, config);
+    });
+}

package/dist/skill-pointer/vault-installer.d.ts

@@ -1,8 +1,10 @@
+import type { RiskLevel } from "./risk-level.js";
 export interface SkillIndexEntry {
     id: string;
     category: string;
     name: string;
     description: string;
+    risk?: RiskLevel;
 }
 /**
  * Loads the pre-built skills_index.json from the project root.

package/dist/skill-pointer/vault-installer.js

@@ -10,6 +10,16 @@ function parseFrontmatterField(content, field) {
     const match = content.match(new RegExp(`^${field}:\\s*["']?([^"'\\n]+)["']?`, "m"));
     return match ? match[1].trim() : "";
 }
+/**
+ * Normalizes a parsed risk value to a valid RiskLevel, or "unknown" if invalid.
+ */
+function normalizeRisk(parsed) {
+    if (!parsed)
+        return "unknown";
+    const lowered = parsed.trim().toLowerCase();
+    const valid = ["none", "safe", "critical", "offensive", "unknown"];
+    return valid.includes(lowered) ? lowered : "unknown";
+}
 /**
  * Derives a category slug from a skill folder name by taking the
  * first hyphen-separated segment (e.g. "laravel-expert" → "laravel",
@@ -40,10 +50,15 @@ function buildIndexFromBundledSkills(bundledSkillsPath) {
         const name = parseFrontmatterField(content, "name") || entry;
         const description = parseFrontmatterField(content, "description") || name;
         const category = parseFrontmatterField(content, "category") || categoryFromFolderName(entry);
-        index.push({ id: entry, category, name, description });
+        const riskRaw = parseFrontmatterField(content, "risk");
+        const risk = normalizeRisk(riskRaw);
+        index.push({ id: entry, category, name, description, risk });
     }
     return index;
 }
+function isSafePathComponent(segment) {
+    return !segment.includes("..") && !segment.includes(path.sep) && !segment.includes("/");
+}
 /**
  * Loads the pre-built skills_index.json from the project root.
  * Falls back to a dynamically generated index from SKILL.md frontmatter
@@ -54,7 +69,10 @@ export function loadSkillsIndex(bundledSkillsPath) {
     if (fs.existsSync(indexPath)) {
         try {
             const raw = fs.readFileSync(indexPath, "utf-8");
-            return JSON.parse(raw);
+            return JSON.parse(raw).map((entry) => ({
+                ...entry,
+                risk: normalizeRisk(entry.risk),
+            }));
         }
         catch {
             // fall through to dynamic generation
@@ -69,17 +87,40 @@ export function loadSkillsIndex(bundledSkillsPath) {
 export function installSkillsToVault(bundledSkillsPath, vaultDir, index) {
     if (!fs.existsSync(bundledSkillsPath))
         return;
-    const categoryMap = new Map(index.map((e) => [e.id, e.category ?? UNCATEGORIZED_CATEGORY]));
-    for (const entry of fs.readdirSync(bundledSkillsPath)) {
-        if (entry.startsWith(".") ||
-            entry === "skills_index.json" ||
-            entry === "README.md")
+    const expected = new Map();
+    for (const entry of index) {
+        if (!isSafePathComponent(entry.id) || !isSafePathComponent(entry.category ?? UNCATEGORIZED_CATEGORY))
+            continue;
+        const category = entry.category ?? UNCATEGORIZED_CATEGORY;
+        if (!expected.has(category))
+            expected.set(category, new Set());
+        expected.get(category).add(entry.id);
+    }
+    if (fs.existsSync(vaultDir)) {
+        for (const category of fs.readdirSync(vaultDir)) {
+            const categoryPath = path.join(vaultDir, category);
+            if (!fs.statSync(categoryPath).isDirectory())
+                continue;
+            const allowedSkills = expected.get(category) ?? new Set();
+            for (const skillId of fs.readdirSync(categoryPath)) {
+                const skillPath = path.join(categoryPath, skillId);
+                if (!allowedSkills.has(skillId)) {
+                    fs.rmSync(skillPath, { recursive: true, force: true });
+                }
+            }
+            if (fs.readdirSync(categoryPath).length === 0) {
+                fs.rmSync(categoryPath, { recursive: true, force: true });
+            }
+        }
+    }
+    for (const entry of index) {
+        if (!isSafePathComponent(entry.id) || !isSafePathComponent(entry.category ?? UNCATEGORIZED_CATEGORY))
             continue;
-        const srcPath = path.join(bundledSkillsPath, entry);
-        if (!fs.statSync(srcPath).isDirectory())
+        const srcPath = path.join(bundledSkillsPath, entry.id);
+        if (!fs.existsSync(srcPath) || !fs.statSync(srcPath).isDirectory())
             continue;
-        const category = categoryMap.get(entry) ?? UNCATEGORIZED_CATEGORY;
-        const destPath = path.join(vaultDir, category, entry);
+        const category = entry.category ?? UNCATEGORIZED_CATEGORY;
+        const destPath = path.join(vaultDir, category, entry.id);
         ensureDir(path.join(vaultDir, category));
         fs.cpSync(srcPath, destPath, { recursive: true, force: true });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "2.0.300",
+  "version": "3.0.0",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "bun test",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -33,12 +34,14 @@
   "author": "Davide Ladisa <info@davideladisa.it>",
   "license": "MIT",
   "dependencies": {
-    "@opencode-ai/plugin": "^1.4.0"
+    "@opencode-ai/plugin": "^1.4.0",
+    "strip-json-comments": "^5.0.3"
   },
   "devDependencies": {
     "@opencode-ai/sdk": "^1.4.0",
     "@types/bun": "latest",
     "@types/node": "^25.5.2",
+    "@types/strip-json-comments": "^3.0.0",
     "typescript": "^6.0.2"
   }
 }