feat: publish as npm package for OpenCode compatibility

[iduartgomez]

Summary

Currently, freenet-agent-skills works seamlessly with Claude Code via the marketplace system. However, OpenCode users need to manually clone the repo to access skills. Publishing as an npm package would provide first-class support for both platforms.

Current State

Claude Code ✅ Works via marketplace
OpenCode ⚠️ Requires manual clone or openskills install freenet/freenet-agent-skills

Proposed Structure

freenet-agent-skills/
├── package.json # npm entry point
├── index.js # OpenCode plugin exports
├── .claude-plugin/marketplace.json # Claude Code (existing)
├── skills/ # Shared (both platforms)
├── agents/ # Future: claude/ and opencode/ subdirs
└── hooks/ # Future: OpenCode JS hooks

Platform Feature Comparison

Feature	Claude Code	OpenCode	Shared?
Skills	.claude/skills/	.opencode/skill/	✅ Yes
Agents	Plugin/.claude/agents/	JS exports	❌ Different
Hooks	settings.json	JS plugin exports	❌ Different
MCP	Plugin config	opencode.json	⚠️ Similar

After Implementation

OpenCode becomes simple:

{ "plugin": ["freenet-agent-skills"] }

Migration Steps

• Add package.json with npm metadata
• Add index.js as OpenCode plugin entry
• Publish to npm
• Update README with dual-platform docs
• (Optional) Platform-specific dirs for agents/hooks

References

Claude Code Plugin Marketplaces
OpenCode Plugins
opencode-agent-skills (reference)

[sanity]

Issue Priority Assessment

Generated: 2026-02-18T22:11:52.052620850+00:00
Issue hash: 0611143e

Value Assessment

The README already advertises this repo as “compatible with Claude Code and OpenCode,” yet the installation steps for OpenCode are still manual cloning and symlinking from README.md, while Claude users get a marketplace experience via .claude-plugin/marketplace.json. That discrepancy means every OpenCode user who wants to try a skill has to manually clone the repo, manage symlinks, and keep their copy in sync—an onerous process compared with Claude’s command like /plugin install freenet-dapp-builder. Publishing to npm would eliminate that friction for the entire OpenCode base and make updates as simple as openskills install freenet/freenet-agent-skills, directly affecting everyone trying to use the shared skills under skills/ with OpenCode.

Strategically, the project is already structured around Claude integrations—the .claude-plugin manifest, Claude hooks in hooks/hooks.json, and the README emphasizing the marketplace workflow—but the skill files under skills/ are explicitly meant to be “shared (both platforms),” so making OpenCode first-class by wiring up package.json and an index.js export would finally match the stated dual-platform commitment. It also unlocks any future platform-specific agents in agents/ or hooks in hooks/ that could reasonably live behind the same npm package, keeping the repo’s architecture unified rather than split between manual installs and Claude-only publishing.

The work doesn’t block existing features, but it does prevent new contributors and users on OpenCode from easily adopting or extending the repo; they either stop at cloning or duplicate the skills within their own Claude directories, which fragments the community around this toolkit. Since Claude’s marketplace is already set up, aligning OpenCode now avoids a growing divergence—new skills will keep landing in skills/, and without npm distribution there’s no low-effort way for OpenCode users to pick them up, meaning any future feature that depends on cross-platform adoption stays starved.

There’s no external deadline, so urgency is low except for the momentum around OpenCode’s plugin model; publishing sooner keeps the dual-platform promise fresh in the project’s messaging and prevents the manual-install workaround from becoming the accepted norm.

Cost Assessment

Publishing this repo as an npm package will mostly touch the packaging/README layer: the install section currently walks OpenCode users through cloning and symlinking the skills/ folders (README.md:92-113), and the repository structure list only calls out .claude-plugin/, skills/, hooks/, and agents/ with no package.json or index.js entry point yet (README.md:116-138). Implementing the proposal therefore entails creating that npm manifest and OpenCode plugin entry at the repo root, and then updating the documentation to describe dual-platform installs while keeping the existing marketplace instructions for Claude.

The technical work centers on making OpenCode consume the same skill assets that Claude already exposes. .claude-plugin/marketplace.json currently registers a single freenet plugin whose skills array references the four directories under skills/ and whose source is ./ (marketplace.json:1-24), so the new index.js will likely need to replicate that mapping in JavaScript and export hooks/agents in the format OpenCode expects. The rest of the repository—agents/ files such as agents/big-picture-reviewer.md are just Markdown instructions (agents/big-picture-reviewer.md:1-143), and the skills themselves live entirely in SKILL.md documents—so there isn’t executable logic to refactor, but you do have to ensure the npm package bundles those directories unchanged while keeping the Claude manifest pointing at the same relative paths.

The risk is mostly around packaging and path expectations. Claude’s hooks rely on ${CLAUDE_PLUGIN_ROOT} as seen in hooks/hooks.json where the only hook command runs ${CLAUDE_PLUGIN_ROOT}/hooks/claude-pre-commit-hook.sh (hooks/hooks.json:1-15), and the marketplace manifest assumes the plugin root contains hooks/, agents/, and the skills/ tree. If the npm packaging restructures directories or omits files, the Claude installation could break immediately and OpenCode might get a malformed export, so the build step that creates package.json/index.js must guarantee those relative layouts remain intact for both ecosystems.

Testing will be manual because the repo currently has no automated test harness—everything is documentation and scripts (e.g., hooks are documented in hooks/README.md:1-120) rather than runnable suites—so you’ll need to validate by actually installing the package in OpenCode, confirming the plugin entry exports the skills, and making sure Claude still sees the marketplace and hooks automatically. That means building the npm package, publishing or linking it locally, and then checking the existing Claude instructions still work, with no built-in regression checks to lean on.

---

Generated by issue-prioritizer