feat(skills): Add opencode-skills package with BM25 ranking by thoroc · Pull Request #24 · pantheon-org/opencode-plugins

thoroc · 2026-01-31T23:05:51Z

Summary

Complete skill injection system with BM25 probabilistic ranking for smart pattern matching.

Changes

Complete skill injection system with BM25 probabilistic ranking
Markdown parsing and validation for skill files
Pattern matching with regex and intent detection
Structured skill format with frontmatter support
Independent package - no internal dependencies
Comprehensive test coverage

BM25 Features

Tokenization and TF-IDF scoring
Probabilistic document ranking
Top-k skill selection
Pattern matching with escape regex utilities

Dependencies

Requires: PR feat(infra): Add Biome linting/formatting infrastructure #21 (Biome infrastructure)
Independent of: PR feat(notification): Add opencode-notification utility package #22, PR feat(config): Add opencode-config utility package #23 (notification and config)

Blocks

PR feat(dev): Add development tools and custom executors #25 (core plugin)

Testing

Tests pass: bunx nx test opencode-skills
Test coverage: bunx nx run opencode-skills:test:coverage
Type-check passes: bunx nx type-check opencode-skills

github-actions · 2026-01-31T23:05:59Z

⚠️ Large PR Warning

This PR is quite large with:

69 changed files
6096 added lines
0 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

Remove all package changes from this PR - they belong in separate PRs: - packages/opencode-agent-loader-plugin/ → PR #28 - packages/opencode-font/ → PR #24 - packages/opencode-warcraft-notifications-plugin/ → PR #29 PR #21 now contains ONLY Biome infrastructure: - biome.json configuration - lefthook.yml git hooks - nx.json targets for lint/format - Root package.json scripts - CI workflow (validate-pr.yml) - Infrastructure executors (typecheck, validate-tsdoc) - Generator templates with Biome config Apply Biome formatting to biome.json (trailing newline).

Remove all packages and dev tools that belong in other PRs: - packages/* (moved to PR #22, #23, #24, etc.) - tools/dev/* (moved to PR #5) - tools/executors/dev-proxy/* (moved to PR #5) - tools/executors/check-mirror-exists/* (moved to PR #5) - tools/executors/validate-skill-md/* (moved to PR #5) - tools/executors/validate-skills/* (moved to PR #5) Keep only Biome infrastructure: - biome.json, lefthook.yml, nx.json, package.json - .github/workflows/validate-pr.yml - libs/workflows/project.json - tools/executors/typecheck/ - tools/executors/validate-tsdoc/ - tools/generators/* (templates with Biome config)

* feat(infra): add Biome linting/formatting infrastructure - Add Biome v2.3.13 configuration with custom rules - Configure lint, format, and format:check targets in nx.json - Add validate-tsdoc executor for documentation validation - Update lefthook.yml with Biome pre-commit hooks - Update validate-pr.yml workflow for Biome - Update generators to include Biome configuration This PR establishes the foundation for Biome-based linting and formatting that all subsequent PRs will use. * fix: resolve CI failures on Biome infrastructure PR - Remove opencode-font override from biome.json to enable linting/formatting - Fix ASCIISiteTitle variable name typo (_siteTitle -> siteTitle) - Fix non-null assertion in load-all-agent-specs.ts using type guard pattern All checks now pass: - Biome linting ✓ - Biome formatting ✓ - docs-builder build ✓ * fix(agent-loader): fix type predicate in load-all-agent-specs.ts Use proper type predicate pattern instead of type assertion for filtering successful agent spec loads. Fixes CI typecheck failure. * fix: resolve remaining CI failures on PR #21 - Fix type predicate in load-all-agent-specs.ts using proper pattern - Fix 2 lint errors in validate-docs-links.ts (noImplicitAnyLet, useIterableCallbackReturn) - Add missing imports to Header.astro (ASCIISiteTitle, SocialIcons, Search, ThemeSelect) Typecheck and lint now pass locally. * style: apply Biome formatting to fix CI errors Apply Biome formatting to 4 package.json files: - packages/opencode-agent-loader-plugin/package.json - packages/opencode-agent-loader-plugin/tsconfig.test.json - packages/opencode-font/package.json - packages/opencode-warcraft-notifications-plugin/package.json Fixes format CI failures on PR #21. * fix(agent-loader): use type assertion instead of type predicate Replace type predicate with type assertion to satisfy stricter CI checks. The filter returns items with defined spec, then we safely assert the type. Fixes typecheck failures on PR #21. * refactor: cleanup PR #21 to only include infrastructure Remove all package changes from this PR - they belong in separate PRs: - packages/opencode-agent-loader-plugin/ → PR #28 - packages/opencode-font/ → PR #24 - packages/opencode-warcraft-notifications-plugin/ → PR #29 PR #21 now contains ONLY Biome infrastructure: - biome.json configuration - lefthook.yml git hooks - nx.json targets for lint/format - Root package.json scripts - CI workflow (validate-pr.yml) - Infrastructure executors (typecheck, validate-tsdoc) - Generator templates with Biome config Apply Biome formatting to biome.json (trailing newline). * fix(biome): add overrides for test/template files to fix lint errors Add Biome linter overrides to allow patterns in test/template files: - Disable noBannedTypes for tools/executors/**/*.test.ts (Function type) - Disable noNamespace for executors and templates - Disable noExplicitAny for generator templates Fixes CI lint failures: - 'Don't use Function as a type' errors - 'TypeScript namespaces are outdated' errors - 'Unexpected any' warnings in templates Also fixes dev-proxy test type assertions. * fix(biome): add file ignores for packages not in this PR Add file ignores to biome.json for packages and tools that belong in other PRs: - packages/opencode-agent-loader-plugin/* - packages/opencode-font/* - packages/opencode-warcraft-notifications-plugin/* - tools/dev/* - tools/executors/dev-proxy/* - tools/executors/check-mirror-exists/* - tools/executors/validate-skill-md/* - tools/executors/validate-skills/* This allows the infrastructure PR to pass CI without linting files that will be properly formatted and fixed in their respective PRs. Also apply Biome formatting to biome.json (trailing newline). * fix(biome): add file ignores and template overrides to fix CI - Add files.includes to ignore packages not in this PR: - packages/opencode-agent-loader-plugin - packages/opencode-font - packages/opencode-warcraft-notifications-plugin - Add linter override for generator template files to disable noExplicitAny - Apply Biome formatting to biome.json Fixes CI lint and format errors. * fix(biome): simplify biome.json configuration to fix CI Remove all package file ignores and use a clean, minimal biome.json that only ignores standard directories (dist, node_modules). This ensures the infrastructure PR can pass CI without trying to lint files that belong in other PRs. All local checks pass: - bun run format:check ✓ - bun run lint ✓ * refactor: clean PR #21 to only include infrastructure Remove all packages and dev tools that belong in other PRs: - packages/* (moved to PR #22, #23, #24, etc.) - tools/dev/* (moved to PR #5) - tools/executors/dev-proxy/* (moved to PR #5) - tools/executors/check-mirror-exists/* (moved to PR #5) - tools/executors/validate-skill-md/* (moved to PR #5) - tools/executors/validate-skills/* (moved to PR #5) Keep only Biome infrastructure: - biome.json, lefthook.yml, nx.json, package.json - .github/workflows/validate-pr.yml - libs/workflows/project.json - tools/executors/typecheck/ - tools/executors/validate-tsdoc/ - tools/generators/* (templates with Biome config) * fix: resolve Biome linting and formatting issues for CI - Updated opencode-font package.json to skip Biome (disabled in root config) - Fixed type predicate for AgentSpecLoadResult to remove non-null assertion - Applied Biome formatting to all JSON files - All checks now pass: lint, format, type-check * fix: add verbose flag to Biome CI command for detailed output * fix(biome): add diagnostic level flag to Biome CI command for improved error reporting * fix: add output-style flag to various nx affected commands for consistent output * docs: add Biome diagnostics reference to skill documentation - Add https://biomejs.dev/reference/diagnostics/ to Getting More Help section * fix(biome): add BIOME_CONFIG_PATH environment variable for Biome CI * fix: update globals.d.ts to ignore linting for noNamespace rule * docs: add debugging guidance for CI failures in Biome skill documentation

- Complete skill injection system with BM25 probabilistic ranking - Markdown parsing and validation for skill files - Pattern matching with regex and intent detection - Structured skill format with frontmatter support - Independent package - no internal dependencies - Required by: opencode-core-plugin This package provides the foundation for smart skill injection and context-aware prompt enhancement.

github-actions · 2026-02-01T21:53:10Z

⚠️ Large PR Warning

This PR is quite large with:

70 changed files
6550 added lines
2 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-01T21:54:58Z

⚠️ Large PR Warning

This PR is quite large with:

70 changed files
6543 added lines
2 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

Copilot

Pull request overview

This PR adds a new opencode-skills package implementing a skill injection system with BM25 probabilistic ranking for intelligent pattern matching. The package provides TypeScript-based skill definitions with automatic injection capabilities.

Changes:

Complete skill injection system with BM25 relevance ranking
Pattern matching with intent detection, negation detection, and keyword support
Markdown parsing with YAML frontmatter for skill files
Validation system for skill definitions
Custom Nx executors for skill validation
Comprehensive test coverage and documentation

Reviewed changes

Copilot reviewed 65 out of 70 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
packages/opencode-skills/src/bm25.ts	BM25 implementation - DUPLICATE of src/bm25/ directory
packages/opencode-skills/src/bm25/*	Modular BM25 implementation with separate files for each function
packages/opencode-skills/src/pattern-matching.ts	Pattern matching implementation - DUPLICATE of src/pattern-matching/ directory
packages/opencode-skills/src/pattern-matching/*	Modular pattern matching with intent/negation detection
packages/opencode-skills/src/parsers/markdown-parser.ts	Markdown parser - DUPLICATE of modular parser files
packages/opencode-skills/src/parsers/*	Modular markdown parser components
packages/opencode-skills/src/validation/*	Skill validation with errors, warnings, and suggestions
packages/opencode-skills/src/create-skills-plugin.ts	Plugin factory function
packages/opencode-skills/src/define-skill.ts	Helper for creating skill objects
packages/opencode-skills/src/examples.ts	Example skills for demonstration
packages/opencode-skills/src/types.ts	Type definitions for skills and configuration
packages/opencode-skills/src/index.ts	Package entry point
tools/executors/validate-skills/*	Nx executor for TypeScript skill validation
tools/executors/validate-skill-md/*	Nx executor for markdown skill validation
packages/opencode-skills/package.json	Package configuration and dependencies
packages/opencode-skills/README.md	Comprehensive documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/opencode-skills/src/examples.ts

packages/opencode-skills/package.json

Copilot · 2026-02-01T21:55:42Z

packages/opencode-skills/package.json

+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"


The csstype and undici-types packages are listed as dependencies but don't appear to be used in the codebase. These should be removed unless there's a specific reason for their inclusion.

Copilot · 2026-02-01T21:55:42Z

tools/executors/validate-skill-md/executor.ts

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises';
+import type { ExecutorContext } from '@nx/devkit';
+import { glob } from 'glob';


Missing dependency: The glob package is imported but not listed in package.json dependencies. This will cause a runtime error when the executor tries to run.

Add glob to the dependencies or devDependencies in package.json, or use a built-in Node.js alternative.

packages/opencode-skills/src/validation/skill-validator.ts

tools/executors/validate-skills/executor.ts

tools/executors/validate-skill-md/executor.ts

packages/opencode-skills/src/pattern-matching.ts

packages/opencode-skills/src/bm25.ts

github-actions · 2026-02-01T22:02:25Z

⚠️ Large PR Warning

This PR is quite large with:

70 changed files
6543 added lines
2 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

…up, deprecated category field

github-actions · 2026-02-01T22:10:45Z

⚠️ Large PR Warning

This PR is quite large with:

71 changed files
6541 added lines
51 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

- Updated ValidationResult to use errors/warnings/suggestions arrays - Added new required Skill fields: whatIDo, whenToUseMe, instructions, checklist - Rewrote validateSkill() to match test expectations - Rewrote formatValidationResult() with skillName parameter - Added validateSkill() and formatValidationResult() exports - All 43 tests now passing

github-actions · 2026-02-02T00:53:27Z

⚠️ Large PR Warning

This PR is quite large with:

71 changed files
6178 added lines
58 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

- Removed strict mode logic that converted warnings to errors - All 43 tests now passing - Build successful

github-actions · 2026-02-02T01:00:58Z

⚠️ Large PR Warning

This PR is quite large with:

71 changed files
6169 added lines
58 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

…s, arrow functions - Split skill-validator.ts into separate modules: - validate-skill.ts: single arrow function - format-validation-result.ts: single arrow function - Updated validation/index.ts barrel exports - Moved test to proper __tests__/ location - All 43 tests passing, build successful

github-actions · 2026-02-02T01:03:45Z

⚠️ Large PR Warning

This PR is quite large with:

70 changed files
5943 added lines
58 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

- Modified validate-skill to accept legacy content field - v2 structured fields only required when legacy content absent - Removed duplicate deprecation warnings - All 58 tests passing, build successful

github-actions · 2026-02-02T01:08:34Z

⚠️ Large PR Warning

This PR is quite large with:

67 changed files
5188 added lines
58 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-02T01:14:03Z

⚠️ Large PR Warning

This PR is quite large with:

67 changed files
5188 added lines
58 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

…irectory

…unctions, unit test collocation, and TDD

- Introduced the subagent-driven development skill with detailed process and advantages. - Added prompt templates for implementer, spec compliance reviewer, and code quality reviewer subagents. - Created a comprehensive test-driven development skill with guidelines and anti-patterns. - Developed a writing plans skill to assist in creating detailed implementation plans.

…eviewer prompt template

…ce skill definitions with licensing, compatibility, and checklists

…eviewer prompt template

…nd improve code organization - Convert 13 named function declarations to arrow functions across all modules - validation/skill-validator.ts: validateSkill - bm25/calculate-score.ts: calculateBM25Score - bm25/build-index.ts: buildBM25Index - bm25/rank-skills.ts: rankSkillsByBM25 - bm25/tokenize.ts: tokenize - bm25/get-top-skills.ts: getTopSkillsByBM25 - parsers/markdown-to-skill.ts: markdownToSkill - parsers/skill-to-markdown.ts: skillToMarkdown - parsers/parse-skill-markdown.ts: parseSkillMarkdown - parsers/extract-frontmatter.ts: extractFrontmatter - parsers/extract-sections.ts: extractSections - pattern-matching/has-intent-to-use.ts: hasIntentToUse - pattern-matching/escape-regex.ts: escapeRegex - pattern-matching/find-matching-skills.ts: findMatchingSkills - create-skills-plugin.ts: createSkillsPlugin - define-skill.ts: defineSkill - examples.ts: validate, MyComponent (documentation) - Remove emojis from validation output format - Replace ❌⚠️💡✅ with [ERROR][WARNING][SUGGESTION][OK] - Decompose extract-sections.ts into smaller modules - Create split-by-headings.ts for heading parsing - Create parse-checklist-items.ts for checklist extraction - Reduce extract-sections.ts from 96 to 46 lines - Delete markdown-parser.ts violating one-function-per-file rule - Functions already exist in separate files - Update markdown-parser.test.ts to import from separate modules - Add comprehensive BM25 unit tests - tokenize.test.ts: 10 test cases - term-frequency.test.ts: 6 test cases - inverse-document-frequency.test.ts: 6 test cases - calculate-score.test.ts: 8 test cases - build-index.test.ts: 7 test cases - Add pattern matching edge case tests - escape-regex.test.ts: 13 test cases - has-intent-to-use.test.ts: 19 test cases - find-matching-skills.test.ts: 14 test cases - Move index.test.ts to define-skill.test.ts (colocation) - Fix markdown-to-skill.ts to include version and updatedAt fields All 114 tests passing

github-actions · 2026-02-02T10:50:28Z

⚠️ Large PR Warning

This PR is quite large with:

95 changed files
9102 added lines
59 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

…dability

github-actions · 2026-02-02T11:28:14Z

⚠️ Large PR Warning

This PR is quite large with:

96 changed files
9115 added lines
63 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-02T11:33:31Z

⚠️ Large PR Warning

This PR is quite large with:

96 changed files
9115 added lines
63 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-02T11:36:51Z

⚠️ Large PR Warning

This PR is quite large with:

97 changed files
9118 added lines
63 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-02T11:38:40Z

⚠️ Large PR Warning

This PR is quite large with:

97 changed files
9120 added lines
63 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-02T11:39:06Z

⚠️ Large PR Warning

This PR is quite large with:

97 changed files
9121 added lines
63 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

thoroc mentioned this pull request Jan 31, 2026

feat(dev): Add development tools and custom executors #25

Merged

2 tasks

This was referenced Jan 31, 2026

feat(core): Add opencode-core-plugin with 6 specialized skills #26

Open

feat(infra): Add Biome linting/formatting infrastructure #21

Merged

thoroc requested a review from Copilot February 1, 2026 21:49

Copilot started reviewing on behalf of thoroc February 1, 2026 21:49 View session

thoroc added 2 commits February 1, 2026 21:52

fix: add missing yaml dependency to opencode-skills

d564311

thoroc force-pushed the feat/pr4-skills-package branch from 97b13fb to d564311 Compare February 1, 2026 21:53

fix: remove non-existent validate:tsdoc target from skills project.json

4e8d5b5

Copilot AI reviewed Feb 1, 2026

View reviewed changes

fix: resolve Biome linting errors in opencode-skills

7e2abbc

fix: address Copilot review comments - glob dependency, package clean…

b1dc53b

…up, deprecated category field

thoroc added 4 commits February 1, 2026 22:15

refactor: remove duplicate type definitions in skill-validator.ts

836d5c9

chore: update lock file after adding glob dependency

f545fc7

fix: add missing types and exports for skill-validator tests

423a9ff

fix: correct strict mode behavior in skill validator

bca6b16

- Removed strict mode logic that converted warnings to errors - All 43 tests now passing - Build successful

refactor: remove unused BM25 and pattern matching implementations

25efcda

fix: support legacy content field for backward compatibility

97b4bf8

- Modified validate-skill to accept legacy content field - v2 structured fields only required when legacy content absent - Removed duplicate deprecation warnings - All 58 tests passing, build successful

style: fix Biome formatting

29ce615

thoroc added 9 commits February 2, 2026 09:52

fix: update .gitignore to include markdown files in OpenCode skills d…

1ca52c1

…irectory

feat: add coding conventions document outlining standards for arrow f…

21e36f3

…unctions, unit test collocation, and TDD

feat: add receiving and requesting code review skills, enhance code r…

1dd0f41

…eviewer prompt template

feat: add out of bounds handling for BM25 score calculation and enhan…

e153762

…ce skill definitions with licensing, compatibility, and checklists

feat: add receiving and requesting code review skills, enhance code r…

8c6fe42

…eviewer prompt template

fix(opencode-skills): add version property to SkillFrontmatter type

4267876

fix(opencode-skills): fix get-top-skills test to use proper threshold

ff8c7a1

thoroc added 5 commits February 2, 2026 11:23

fix(pr-iteration): clean up formatting and add spacing for better rea…

fb2a4f8

…dability

fix: add missing newline at end of files in prompt templates

91bb584

fix: standardize quotes and formatting in TDD examples

a705551

fix: update MD024 rule to disable duplicate heading check

515e16b

fix: include AGENTS.md in markdownlint globs for documentation linting

3e68114

fix: update import paths for markdown parser and skill validator

8795d74

thoroc added 2 commits February 2, 2026 11:35

fix: add path mapping for opencode-skills in tsconfig

bc399ec

style: fix biome linting errors in config and executor

dc1e4db

style: apply biome fixes to tools/executors/validate-skills

bda64c6

thoroc merged commit e9e244b into main Feb 2, 2026
5 checks passed

thoroc deleted the feat/pr4-skills-package branch February 2, 2026 11:48

Conversation

thoroc commented Jan 31, 2026

Summary

Changes

BM25 Features

Dependencies

Blocks

Testing

Uh oh!

github-actions bot commented Jan 31, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

github-actions bot commented Feb 2, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant