{"id":51241400,"url":"https://github.com/felipegenef/opencode-lazy-skills","last_synced_at":"2026-06-29T00:32:25.026Z","repository":{"id":365373496,"uuid":"1271695329","full_name":"felipegenef/opencode-lazy-skills","owner":"felipegenef","description":"A simple opencode plugin to help lazyloading skills for better token efficiency","archived":false,"fork":false,"pushed_at":"2026-06-17T04:26:52.000Z","size":56,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T05:14:04.123Z","etag":null,"topics":["ai","ai-agents","efficiency","opencode","opencode-plugin","opensource","token-optimization"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felipegenef.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-16T23:34:29.000Z","updated_at":"2026-06-17T04:26:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/felipegenef/opencode-lazy-skills","commit_stats":null,"previous_names":["felipegenef/opencode-lazy-skills"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/felipegenef/opencode-lazy-skills","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipegenef%2Fopencode-lazy-skills","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipegenef%2Fopencode-lazy-skills/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipegenef%2Fopencode-lazy-skills/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipegenef%2Fopencode-lazy-skills/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felipegenef","download_url":"https://codeload.github.com/felipegenef/opencode-lazy-skills/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felipegenef%2Fopencode-lazy-skills/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34909137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","efficiency","opencode","opencode-plugin","opensource","token-optimization"],"created_at":"2026-06-29T00:32:22.873Z","updated_at":"2026-06-29T00:32:25.017Z","avatar_url":"https://github.com/felipegenef.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-lazy-skills\n\n\u003e Lazy-loads opencode skills: swaps the always-on `\u003cavailable_skills\u003e` catalog for on-demand\n\u003e skill search and loading, so you pay for the skills you actually use — not the whole catalog\n\u003e on every turn.\n\u003e\n\u003e - **Optimized token usage** — skills are discovered on demand instead of listed on every turn.\n\u003e - **Works alongside opencode's native `skill` tool** rather than replacing it.\n\u003e - **Brings the skill feature to older opencode versions** that don't ship the native tool.\n\n## The problem\n\nOpencode injects an `\u003cavailable_skills\u003e` catalog into **every** agent's system prompt,\nlisting every installed skill's name and description — on every request, whether the agent\nneeds a skill or not. With a large skill collection that is a lot of tokens, burned before\nthe agent has done anything.\n\n```\nBEFORE (without plugin) ── every system prompt includes:\n┌────────────────────────────────────────────────────────┐\n│ You are opencode, an interactive CLI tool...            │\n│ # Tone and style...                                     │\n│ # Proactiveness...                                      │\n│ # Doing tasks...                                        │\n│ \u003cavailable_skills\u003e                                      │\n│   \u003cskill name=\"recipe-coffee\"... /\u003e                     │\n│   \u003cskill name=\"chess-openings\"... /\u003e                    │\n│   \u003cskill name=\"bicycle-maintenance\"... /\u003e               │\n│   \u003c!-- ... many many tokens that go to waste ... --\u003e    │\n│ \u003c/available_skills\u003e                                     │\n└────────────────────────────────────────────────────────┘\n\nAFTER (with plugin) ── catalog replaced by a short on-demand note:\n┌────────────────────────────────────────────────────────┐\n│ You are opencode, an interactive CLI tool...            │\n│ # Tone and style...                                     │\n│ # Proactiveness...                                      │\n│ # Doing tasks...                                        │\n│ \u003cskills\u003e                                                │\n│   Specialized skills are available on demand.           │\n│   - skillsearch \u003ctopic\u003e  → find skills (names only)     │\n│   - skillinfo \u003cname\u003e     → read a skill's description   │\n│   - skill \u003cname\u003e         → load its instructions        │\n│ \u003c/skills\u003e                                               │\n└────────────────────────────────────────────────────────┘\nThe full catalog (and its tokens) is gone; the agent fetches only\nthe one skill it actually needs, only when it needs it.\n```\n\nSee [`examples/full-opencode-system-prompt.md`](examples/full-opencode-system-prompt.md) for a real,\ncomplete opencode system prompt — including the full `\u003cavailable_skills\u003e` catalog that this plugin\nstrips out (the `BEFORE` block above is an abbreviated version of it).\n\n## What this plugin does\n\n1. **Replaces the catalog with a one-line instruction.** The `\u003cavailable_skills\u003e` block is\n   stripped from the system prompt and replaced with a short note telling the agent that skills\n   exist and how to find them on demand. You pay for the skills you actually use, not the whole\n   catalog on every turn.\n2. **Adds `skillsearch`** — keyword discovery that returns matching skill **names only**, keeping\n   the search cheap no matter how many skills match. opencode has no native equivalent.\n3. **Adds `skillinfo`** — fetches a skill's description on demand, so the agent can confirm a\n   match before paying to load the whole skill.\n4. **Provides `skill` only when opencode doesn't.** See below.\n\n## Works *with* opencode's native skill tool\n\nSince v1.16.0, opencode ships its own `skill` tool. This plugin detects that and gets out of\nits way:\n\n| Your opencode version | Loading a skill | Why |\n|-----------------------|-----------------|-----|\n| **≥ 1.16.0** | opencode's **native** `skill` tool | It already exists and discovers skills from more locations (including `~/.claude/skills` and skill URLs). We defer to it. |\n| **\u003c 1.16.0** | this plugin's **`skill` polyfill** | No native tool exists, so we register one whose name, arguments **and output are matched to native's** (inline `\u003cskill_content\u003e` with the skill's base directory and file list). Upgrading opencode later changes nothing you can see. |\n\nEither way, `skillsearch` is always provided, and the catalog-replacement instruction refers to\n`skill` — which resolves to whichever tool is active. A loaded skill reports its base directory\nand file paths, so any resource files (`scripts/`, `assets/`, `references/`) are read with\nopencode's normal file-read tool — exactly as the native `skill` tool intends.\n\n### Which tool you get\n\nDetection is automatic — it reads your installed opencode version and uses the native `skill`\ntool from 1.16.0 onward, the polyfill below it. You don't need to configure anything. If your\nversion can't be determined, it falls back to the polyfill, which is always safe.\n\nTo force a branch, set an environment variable:\n\n```bash\nOPENCODE_SKILL_POLYFILL=off   # always defer to opencode's native skill tool\nOPENCODE_SKILL_POLYFILL=on    # always use this plugin's skill polyfill\n```\n\n## Install\n\n```bash\nopencode plugin @felipegenef/opencode-lazy-skills --global\n```\n\n## Updating\n\nOpencode resolves this plugin to whatever `latest` was at install time and caches it locally —\nit does **not** re-check the registry on later launches. Worse, the cache keeps a pinned\n`package.json` + `package-lock.json` (e.g. `\"@felipegenef/opencode-lazy-skills\": \"1.0.0\"`), so\neven `--force` can see the pin already satisfied and install nothing. The reliable way to pick up\na new release is to **delete the cached folder first, then re-install**:\n\n```bash\nrm -rf ~/.cache/opencode/packages/@felipegenef/opencode-lazy-skills@latest\nopencode plugin @felipegenef/opencode-lazy-skills --global --force\n```\n\nDeleting the folder forces opencode to rebuild the cache from scratch and re-resolve `latest`. To\nconfirm afterwards, check the installed version:\n\n```bash\ncat ~/.cache/opencode/packages/@felipegenef/opencode-lazy-skills@latest/node_modules/@felipegenef/opencode-lazy-skills/package.json | grep version\n```\n\n(`--force` on its own only helps when no pinned lockfile is present; without it, opencode skips\nre-fetching entirely.)\n\n## Uninstalling\n\nRemove the plugin entry from the `plugin` array in your opencode config\n(`~/.config/opencode/opencode.jsonc` for a global install, or `.opencode/opencode.jsonc` for a\nproject-local one):\n\n```jsonc\n{\n  \"plugin\": [\n    \"@felipegenef/opencode-lazy-skills\"  // ← delete this line\n  ]\n}\n```\n\nOn the next launch opencode stops loading the plugin and the original `\u003cavailable_skills\u003e` catalog\nis back in the system prompt. To also drop the cached package from disk, delete its folder:\n\n```bash\nrm -rf ~/.cache/opencode/packages/@felipegenef/opencode-lazy-skills@latest\n```\n\n## Tools\n\n| Tool | What it does | Always available? |\n|------|--------------|-------------------|\n| `skillsearch` | Search skills by topic — returns matching **names only** (token-cheap) | Yes |\n| `skillinfo` | Return the **description(s)** for one or more named skills, without loading them | Yes |\n| `skill` | Load a skill's full content into context (and report its base directory + file paths) | Native on ≥1.16.0; polyfill on \u003c1.16.0 |\n\nA typical session:\n\n```\nAgent: \"I need to write Go tests. Let me find the right skill.\"\n  → skillsearch(\"go testing\")\n\nPlugin returns names only:\n   - go-testing\n   - go-benchmarking\n\nAgent: \"The name fits, but let me confirm before loading.\"\n  → skillinfo(\"go-testing\")\n\nPlugin returns:\n   - go-testing: Table-driven tests, subtests, parallel, testdata...\n\nAgent: \"That's the one. Load it.\"\n  → skill({ name: \"go-testing\" })\n\nThe skill's full content is now in context, along with its base\ndirectory and the paths of any bundled files.\n\nAgent: \"Grab the test helper script that skill mentioned.\"\n  → read(\"/path/to/go-testing/scripts/testutil.go\")   (opencode's built-in read tool)\n```\n\n## Skills directory\n\nPlace `SKILL.md` files in:\n\n- `~/.config/opencode/skills/` — global\n- `.opencode/skills/` — project-local (takes priority)\n\n## Configuration\n\nBy default, the plugin discovers skills from these directories (in order):\n\n| Priority | Path |\n|----------|------|\n| 1st | `$XDG_CONFIG_HOME/opencode/skills/` (if set) |\n| 2nd | `~/.config/opencode/skills/` |\n| 3rd | `~/.opencode/skills/` |\n| 4th | `.opencode/skills/` (project-local, always appended) |\n\nTo override, create `.opencode-skillful.json` in your project root:\n\n```json\n{\n  \"debug\": false,\n  \"basePaths\": [\"~/.config/opencode/skills\", \".opencode/skills\"]\n}\n```\n\n## Building\n\n```bash\nbun install\nbun run build    # produces dist/\nbun test\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipegenef%2Fopencode-lazy-skills","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelipegenef%2Fopencode-lazy-skills","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelipegenef%2Fopencode-lazy-skills/lists"}