opencode-skills-collection 3.0.51 → 3.1.0

package/README.md

@@ -21,7 +21,7 @@
 
 ## Overview
 
-**OpenCode Skills Collection** ships a pre-bundled snapshot of 1000+ universal skills for the OpenCode CLI.
+**OpenCode Skills Collection** ships a pre-bundled snapshot of 1595+ universal skills for the OpenCode CLI.
 
 Instead of loading every skill into the AI context at startup — which would consume ~80k tokens and cause compaction
 loops — the plugin uses a **SkillPointer** architecture: skills are organized into categories inside a hidden vault and
@@ -45,7 +45,10 @@ bundled-skills/ (npm package)
         │
         └── SkillPointer pipeline
               │
-              ├─ vault-manager     → moves raw skills to the vault
+              ├─ risk-filter       → excludes skills by risk level or ID
+              ├─ content-scanner   → quarantines skills with dangerous patterns
+              ├─ vault-manager     → moves safe skills to the vault
+              ├─ skill-patcher     → applies config-driven content patches
               └─ pointer-generator → writes ~35 lightweight pointer files
 ```
 
@@ -61,24 +64,19 @@ The full skill content is only injected into context when the AI actually needs
 
 After the first startup, your `~/.config/opencode/` directory looks like this:
 
-```
 ~/.config/opencode/
 ├── opencode.json
-├── skills/                          ← pointer folders (active, read by OpenCode)
+├── skill-filter.jsonc                ← optional: risk filter + patcher config
+├── skills/                           ← pointer folders (active, read by OpenCode)
 │   ├── backend-dev-category-pointer/
 │   │   └── SKILL.md
-│   ├── devops-category-pointer/
-│   │   └── SKILL.md
 │   └── ...
-└── skill-libraries/                 ← vault with all raw skills (hidden from startup context)
+└── skill-libraries/                  ← vault with all raw skills
     ├── backend-dev/
     │   ├── laravel-expert/
     │   │   └── SKILL.md
-    │   └── wordpress-core/
-    │       └── SKILL.md
-    ├── devops/
+    │   └── ...
     └── ...
-```
 
 ---
 
@@ -138,7 +136,7 @@ opencode run /refactor clean up this function
 
 ---
 
-## Skill Risk Filter
+## Skill Safety & Filtering
 
 The plugin supports configurable risk-based filtering of skills. By default, **all skills are loaded** — filtering is
 opt-in.
@@ -169,6 +167,40 @@ Create a `~/.config/opencode/skill-filter.jsonc` file:
 
 Blocked skills are excluded from both the vault and the generated pointers — they are never loaded into context.
 
+### Content Safety Scanner (CI)
+
+Dangerous skills are automatically detected and removed **at build time** — before the npm package is published.
+The nightly sync workflow scans every SKILL.md for recursive loop patterns and strips matching skills from
+`bundled-skills/` and `skills_index.json`, so they never reach end users.
+
+**Built-in patterns detect:**
+- Recursive skill invocation loops ("invoke skills before any response")
+- Aggressive match thresholds ("even a 1% chance")
+- Mandatory pre-response skill checks ("you must invoke the skill")
+
+### Skill Patcher
+
+The plugin can modify skill content after installation via config-driven patches. This allows neutralizing
+problematic instructions without forking upstream skills.
+
+Add patches in `skill-filter.jsonc`:
+
+```jsonc
+{
+  "skillPatches": [
+    {
+      "skillId": "some-skill-name",
+      "find": "regex-pattern-to-match",
+      "replace": "replacement-text",
+      "description": "Why this patch exists"
+    }
+  ]
+}
+```
+
+Patches are applied in order, case-insensitive, and globally (all occurrences). Invalid regex patterns are
+skipped silently. Re-running the pipeline with the same patches is idempotent.
+
 ---
 
 ## Development

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

@@ -1,7 +1,21 @@
 import type { RiskLevel } from "./risk-level.js";
+export interface ScanPattern {
+    id: string;
+    pattern: string;
+    description: string;
+    severity: "block" | "warn";
+}
+export interface SkillPatch {
+    skillId: string;
+    find: string;
+    replace: string;
+    description?: string;
+}
 export interface SkillRiskFilterConfig {
     excludedRiskLevels?: RiskLevel[];
     excludedSkills?: string[];
+    scanPatterns?: ScanPattern[];
+    skillPatches?: SkillPatch[];
 }
 export declare const DEFAULT_FILTER_CONFIG_PATH: string;
 /**

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

@@ -1,13 +1,34 @@
-import os from "os";
-import path from "path";
-import fs from "fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
 import stripJsonComments from "strip-json-comments";
 const DEFAULT_CONFIG = {
     excludedRiskLevels: [],
     excludedSkills: [],
+    scanPatterns: [],
+    skillPatches: [],
 };
 export const DEFAULT_FILTER_CONFIG_PATH = path.join(os.homedir(), ".config", "opencode", "skill-filter.jsonc");
 const VALID_RISK_LEVELS = ["none", "safe", "critical", "offensive", "unknown"];
+const VALID_SEVERITIES = ["block", "warn"];
+function isValidScanPattern(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const obj = entry;
+    return (typeof obj.id === "string" &&
+        typeof obj.pattern === "string" &&
+        typeof obj.description === "string" &&
+        typeof obj.severity === "string" &&
+        VALID_SEVERITIES.includes(obj.severity));
+}
+function isValidSkillPatch(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const obj = entry;
+    return (typeof obj.skillId === "string" &&
+        typeof obj.find === "string" &&
+        typeof obj.replace === "string");
+}
 /**
  * Loads filter config from skill-filter.jsonc. Missing file or section returns defaults.
  * @param configPath Optional override (for testing).
@@ -28,6 +49,12 @@ export function loadFilterConfig(configPath) {
             excludedSkills: Array.isArray(parsed.excludedSkills)
                 ? parsed.excludedSkills
                 : DEFAULT_CONFIG.excludedSkills,
+            scanPatterns: Array.isArray(parsed.scanPatterns)
+                ? parsed.scanPatterns.filter(isValidScanPattern)
+                : DEFAULT_CONFIG.scanPatterns,
+            skillPatches: Array.isArray(parsed.skillPatches)
+                ? parsed.skillPatches.filter(isValidSkillPatch)
+                : DEFAULT_CONFIG.skillPatches,
         };
     }
     catch {

package/dist/skill-pointer/content-scanner.d.ts

@@ -0,0 +1,38 @@
+import type { ScanPattern } from "./config-loader.js";
+import type { SkillIndexEntry } from "./vault-installer.js";
+export interface ScanResult {
+    skillId: string;
+    matchedPatterns: {
+        id: string;
+        severity: "block" | "warn";
+    }[];
+    blocked: boolean;
+}
+export interface ScanOutput {
+    passed: SkillIndexEntry[];
+    quarantined: ScanResult[];
+    warned: ScanResult[];
+}
+/** Default patterns that detect recursive loop triggers in skill content. */
+export declare const DEFAULT_SCAN_PATTERNS: ScanPattern[];
+/**
+ * Merges user-supplied scan patterns with built-in defaults.
+ * Config patterns with the same `id` override the default entry,
+ * but only if the config pattern has a valid regex. Invalid overrides
+ * are rejected and the default is preserved to prevent silently
+ * disabling built-in protection.
+ */
+export declare function mergePatterns(configPatterns: ScanPattern[]): ScanPattern[];
+/**
+ * Tests skill content against a list of scan patterns.
+ * Returns the list of matched pattern ids and severities.
+ */
+export declare function scanSkillContent(content: string, patterns: ScanPattern[]): {
+    id: string;
+    severity: "block" | "warn";
+}[];
+/**
+ * Scans every skill's SKILL.md for dangerous content patterns.
+ * Returns lists of passed, quarantined (blocked), and warned entries.
+ */
+export declare function scanSkills(bundledSkillsPath: string, index: SkillIndexEntry[], configPatterns?: ScanPattern[]): ScanOutput;

package/dist/skill-pointer/content-scanner.js

@@ -0,0 +1,118 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SKILL_FILENAME } from "../constants/constants.js";
+/** Default patterns that detect recursive loop triggers in skill content. */
+export const DEFAULT_SCAN_PATTERNS = [
+    {
+        id: "recursive-skill-invocation",
+        pattern: String.raw `(invoke|use|check|load)\b.*?\bskills?\b.*?\bbefore\s+(any|every|all)\s+(response|action|message)`,
+        description: "Detects instructions mandating skill invocation before every response",
+        severity: "block",
+    },
+    {
+        id: "aggressive-match-threshold",
+        pattern: String.raw `(even\s+)?(a\s+)?1%\s+chance.*skill`,
+        description: "Detects extremely low probability thresholds causing over-triggering",
+        severity: "block",
+    },
+    {
+        id: "mandatory-pre-response-skill-check",
+        pattern: String.raw `you\s+(absolutely\s+)?must.*invoke.*skill`,
+        description: "Detects mandatory skill invocation directives",
+        severity: "block",
+    },
+];
+/**
+ * Merges user-supplied scan patterns with built-in defaults.
+ * Config patterns with the same `id` override the default entry,
+ * but only if the config pattern has a valid regex. Invalid overrides
+ * are rejected and the default is preserved to prevent silently
+ * disabling built-in protection.
+ */
+export function mergePatterns(configPatterns) {
+    const merged = new Map();
+    for (const p of DEFAULT_SCAN_PATTERNS) {
+        merged.set(p.id, p);
+    }
+    for (const p of configPatterns) {
+        // Validate regex before allowing override
+        try {
+            new RegExp(p.pattern, "is");
+            merged.set(p.id, p);
+        }
+        catch {
+            // If this would override a default, keep the default — don't silently disable protection
+            if (!merged.has(p.id)) {
+                // New pattern with invalid regex — just skip it
+                console.warn(`Invalid regex for pattern '${p.id}': ${p.pattern}`);
+            }
+            // Existing default stays in place
+        }
+    }
+    return [...merged.values()];
+}
+/**
+ * Tests skill content against a list of scan patterns.
+ * Returns the list of matched pattern ids and severities.
+ */
+export function scanSkillContent(content, patterns) {
+    const matches = [];
+    for (const p of patterns) {
+        try {
+            const re = new RegExp(p.pattern, "is");
+            if (re.test(content)) {
+                matches.push({ id: p.id, severity: p.severity });
+            }
+        }
+        catch {
+            // Invalid regex — skip silently
+        }
+    }
+    return matches;
+}
+/**
+ * Scans every skill's SKILL.md for dangerous content patterns.
+ * Returns lists of passed, quarantined (blocked), and warned entries.
+ */
+export function scanSkills(bundledSkillsPath, index, configPatterns) {
+    const patterns = mergePatterns(configPatterns ?? []);
+    const passed = [];
+    const quarantined = [];
+    const warned = [];
+    for (const entry of index) {
+        // Path traversal guard: quarantine entries whose id escapes the bundled-skills directory
+        if (entry.id.includes("..") || entry.id.includes(path.sep) || entry.id.includes("/")) {
+            quarantined.push({
+                skillId: entry.id,
+                matchedPatterns: [{ id: "path-traversal", severity: "block" }],
+                blocked: true,
+            });
+            continue;
+        }
+        const skillFile = path.join(bundledSkillsPath, entry.id, SKILL_FILENAME);
+        if (!fs.existsSync(skillFile)) {
+            passed.push(entry);
+            continue;
+        }
+        const content = fs.readFileSync(skillFile, "utf-8");
+        const matches = scanSkillContent(content, patterns);
+        if (matches.length === 0) {
+            passed.push(entry);
+            continue;
+        }
+        const hasBlock = matches.some((m) => m.severity === "block");
+        const result = {
+            skillId: entry.id,
+            matchedPatterns: matches,
+            blocked: hasBlock,
+        };
+        if (hasBlock) {
+            quarantined.push(result);
+        }
+        else {
+            warned.push(result);
+            passed.push(entry);
+        }
+    }
+    return { passed, quarantined, warned };
+}

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

@@ -17,10 +17,15 @@ export interface SkillPointerOptions {
  * Orchestrates the full SkillPointer pipeline:
  *
  * 1. Reads skills_index.json bundled alongside the skills snapshot.
- * 2. Copies bundled skills directly into the vault, categorised by the index.
- * 3. Generates pointer SKILL.md files in activeSkillsDir with full skill
+ * 2. Filters by risk level / excluded skills.
+ * 3. Copies skills into the vault, categorised by the index.
+ * 4. Applies config-driven content patches to installed skills.
+ * 5. Generates pointer SKILL.md files in activeSkillsDir with full skill
  *    listings so keyword searches (e.g. "laravel") resolve out of the box.
  *
+ * Content safety scanning is performed at CI time (sync-skills.yml),
+ * not at runtime — dangerous skills are removed before npm publish.
+ *
  * The activeSkillsDir is never used as a staging area — user custom
  * skills already present there are never moved or overwritten.
  */

package/dist/skill-pointer/index.js

@@ -1,11 +1,12 @@
-import os from "os";
-import path from "path";
+import * as os from "node:os";
+import * as path from "node:path";
 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";
+import { applySkillPatches } from "./skill-patcher.js";
 function resolveDefaultVaultDir() {
     return path.join(os.homedir(), ".config", "opencode", VAULT_DIR_NAME);
 }
@@ -13,10 +14,15 @@ function resolveDefaultVaultDir() {
  * Orchestrates the full SkillPointer pipeline:
  *
  * 1. Reads skills_index.json bundled alongside the skills snapshot.
- * 2. Copies bundled skills directly into the vault, categorised by the index.
- * 3. Generates pointer SKILL.md files in activeSkillsDir with full skill
+ * 2. Filters by risk level / excluded skills.
+ * 3. Copies skills into the vault, categorised by the index.
+ * 4. Applies config-driven content patches to installed skills.
+ * 5. Generates pointer SKILL.md files in activeSkillsDir with full skill
  *    listings so keyword searches (e.g. "laravel") resolve out of the box.
  *
+ * Content safety scanning is performed at CI time (sync-skills.yml),
+ * not at runtime — dangerous skills are removed before npm publish.
+ *
  * The activeSkillsDir is never used as a staging area — user custom
  * skills already present there are never moved or overwritten.
  */
@@ -29,5 +35,9 @@ export function runSkillPointer(options) {
     const config = loadFilterConfig(configPath);
     const filteredIndex = filterIndex(index, config);
     installSkillsToVault(options.bundledSkillsPath, vaultDir, filteredIndex);
+    // Apply content patches
+    if (config.skillPatches && config.skillPatches.length > 0) {
+        applySkillPatches(vaultDir, filteredIndex, config.skillPatches);
+    }
     generatePointers(options.activeSkillsDir, vaultDir, filteredIndex);
 }

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

@@ -35,6 +35,8 @@ ${skillList}
 **Vault path:** \`${normalizedPath}\`
 
 > Do not guess best practices — always read from the vault first.
+
+> ⚠️ **Anti-loop guard**: Do NOT invoke skills recursively or check for applicable skills before every response. Each skill should be loaded at most once per user request. If you have already identified and loaded the relevant skill for this task, proceed with execution — do not re-scan for skills.
 `;
 }
 /**

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

@@ -0,0 +1,13 @@
+import type { SkillPatch } from "./config-loader.js";
+import type { SkillIndexEntry } from "./vault-installer.js";
+/**
+ * Applies regex-based content patches to installed skill files in the vault.
+ *
+ * Each patch targets a `skillId`, performing a case-insensitive global regex
+ * replacement on the skill's SKILL.md content. Multiple patches for the same
+ * skill are applied in order. Invalid regex patterns are silently skipped.
+ *
+ * This function is idempotent — re-running with the same patches on already-patched
+ * content produces no further changes (the regex simply won't match).
+ */
+export declare function applySkillPatches(vaultDir: string, index: SkillIndexEntry[], patches: SkillPatch[]): void;

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

@@ -0,0 +1,99 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SKILL_FILENAME } from "../constants/constants.js";
+/**
+ * Checks whether a path component is safe (no traversal sequences).
+ */
+function isSafePath(component) {
+    return !component.includes("..") && !component.includes("/") && !component.includes(path.sep);
+}
+/**
+ * Resolves the SKILL.md file path for a given index entry within the vault.
+ * Returns `undefined` if the path is unsafe or the file does not exist.
+ */
+function resolveSkillFile(vaultDir, entry) {
+    if (!isSafePath(entry.id) || !isSafePath(entry.category))
+        return undefined;
+    const skillFile = path.join(vaultDir, entry.category, entry.id, SKILL_FILENAME);
+    if (!fs.existsSync(skillFile))
+        return undefined;
+    const resolvedVault = fs.realpathSync(vaultDir);
+    const realSkillFile = fs.realpathSync(skillFile);
+    if (!realSkillFile.startsWith(resolvedVault + path.sep))
+        return undefined;
+    return skillFile;
+}
+/**
+ * Applies a single patch to content, returning the modified content.
+ * Returns `undefined` if the patch could not be applied (invalid regex, empty find, no match).
+ */
+function applySinglePatch(content, patch) {
+    if (!patch.find)
+        return undefined;
+    try {
+        const re = new RegExp(patch.find, "gis");
+        // Use function replacement to treat patch.replace as a literal string
+        // (avoids $& $1 $` $' being interpreted as special replacement patterns)
+        const replacement = patch.replace;
+        const newContent = content.replace(re, () => replacement);
+        return newContent === content ? undefined : newContent;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Groups patches by skillId, preserving order within each group.
+ */
+function groupPatchesBySkill(patches) {
+    const grouped = new Map();
+    for (const patch of patches) {
+        const group = grouped.get(patch.skillId);
+        if (group) {
+            group.push(patch);
+        }
+        else {
+            grouped.set(patch.skillId, [patch]);
+        }
+    }
+    return grouped;
+}
+/**
+ * Applies regex-based content patches to installed skill files in the vault.
+ *
+ * Each patch targets a `skillId`, performing a case-insensitive global regex
+ * replacement on the skill's SKILL.md content. Multiple patches for the same
+ * skill are applied in order. Invalid regex patterns are silently skipped.
+ *
+ * This function is idempotent — re-running with the same patches on already-patched
+ * content produces no further changes (the regex simply won't match).
+ */
+export function applySkillPatches(vaultDir, index, patches) {
+    if (patches.length === 0)
+        return;
+    const entryById = new Map();
+    for (const entry of index) {
+        entryById.set(entry.id, entry);
+    }
+    const patchesBySkill = groupPatchesBySkill(patches);
+    for (const [skillId, skillPatches] of patchesBySkill) {
+        const entry = entryById.get(skillId);
+        if (!entry)
+            continue;
+        const skillFile = resolveSkillFile(vaultDir, entry);
+        if (!skillFile)
+            continue;
+        let content = fs.readFileSync(skillFile, "utf-8");
+        let modified = false;
+        for (const patch of skillPatches) {
+            const result = applySinglePatch(content, patch);
+            if (result !== undefined) {
+                content = result;
+                modified = true;
+            }
+        }
+        if (modified) {
+            fs.writeFileSync(skillFile, content, "utf-8");
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-skills-collection",
-  "version": "3.0.51",
+  "version": "3.1.0",
   "description": "OpenCode CLI plugin that automatically downloads and keeps skills up to date.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",