{"_id":"@civaapple/qi-skills","_rev":"2-54555021ceb2783a3f078f7ae1b3fdab","name":"@civaapple/qi-skills","dist-tags":{"latest":"0.5.1"},"versions":{"0.5.0":{"name":"@civaapple/qi-skills","version":"0.5.0","license":"MIT","_id":"@civaapple/qi-skills@0.5.0","maintainers":[{"name":"civaapple","email":"civaapple@gmail.com"}],"homepage":"https://github.com/civaapple-alt/qi#readme","bugs":{"url":"https://github.com/civaapple-alt/qi/issues"},"dist":{"shasum":"d748fdba23f3465e1bac8374c3e8a908f30e99e1","tarball":"https://registry.npmjs.org/@civaapple/qi-skills/-/qi-skills-0.5.0.tgz","fileCount":24,"integrity":"sha512-bPtng14mCP9sb+83Coe2SjTP5isGGwveYYVTCLhL35yb++ddz/9Uk4Xn8E9+MRgPJWWHx9qgW2DlzZtNcIqusA==","signatures":[{"sig":"MEMCIDT6BlcnHDzj3kEDnjot/PBeXvDYP/5mYf8X+g3Ir5DwAh9NATOow0HZDPXZ3Kt75GTGBjfS6mQUW9KbAH7V/Dqn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@civaapple%2fqi-skills@0.5.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":93292},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.19.0"},"exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"9ae76a92cdcce130958d3f93c6ab5ba20149d424","_npmUser":{"name":"civaapple","email":"civaapple@gmail.com"},"repository":{"url":"git+https://github.com/civaapple-alt/qi.git","type":"git","directory":"packages/skills"},"_npmVersion":"11.16.0","description":"Safe progressive loading of declarative Agent and Skill definitions","directories":{},"_nodeVersion":"24.18.0","dependencies":{"yaml":"2.9.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/qi-skills_0.5.0_1785137633136_0.2696710783262608","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@civaapple/qi-skills","version":"0.5.1","description":"Safe progressive loading of declarative Agent and Skill definitions","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"engines":{"node":">=22.19.0"},"dependencies":{"yaml":"2.9.0"},"repository":{"type":"git","url":"git+https://github.com/civaapple-alt/qi.git","directory":"packages/skills"},"homepage":"https://github.com/civaapple-alt/qi#readme","bugs":{"url":"https://github.com/civaapple-alt/qi/issues"},"license":"MIT","publishConfig":{"access":"public","provenance":true},"gitHead":"8b042be6fb43eda223b619286e9b3e5cb1e1c439","_id":"@civaapple/qi-skills@0.5.1","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-uCy49oNV0x9m0ODk1XPl41AG3sBwc5zWO1EwbotLjDvpoUzZ3a6nnof73ZIIrUXqUyFMilkJuVN7uQoFOLleYQ==","shasum":"3fe3d13d069aa664bc4fdf2fa7d064ff75429ffe","tarball":"https://registry.npmjs.org/@civaapple/qi-skills/-/qi-skills-0.5.1.tgz","fileCount":24,"unpackedSize":112015,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@civaapple%2fqi-skills@0.5.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICiavMZN7LHjd/5EgWYitv9t7fjDsVUf8wC3bG0jUk7XAiEAzVLSWuOnuanRZqqpZD0bHAL7M/hTcw0lS3d6sx69GJI="}]},"_npmUser":{"name":"civaapple","email":"civaapple@gmail.com"},"directories":{},"maintainers":[{"name":"civaapple","email":"civaapple@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qi-skills_0.5.1_1785149293599_0.11010007859899407"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-27T07:33:52.943Z","modified":"2026-07-27T10:48:14.100Z","0.5.0":"2026-07-27T07:33:53.279Z","0.5.1":"2026-07-27T10:48:13.737Z"},"bugs":{"url":"https://github.com/civaapple-alt/qi/issues"},"license":"MIT","homepage":"https://github.com/civaapple-alt/qi#readme","repository":{"type":"git","url":"git+https://github.com/civaapple-alt/qi.git","directory":"packages/skills"},"description":"Safe progressive loading of declarative Agent and Skill definitions","maintainers":[{"name":"civaapple","email":"civaapple@gmail.com"}],"readme":"# `@civaapple/qi-skills`\n\nSafe progressive loading of declarative Skills and Agent definitions from the filesystem.\n\n## Purpose\n\nThis package discovers lightweight metadata first and loads full instructions or resources only when selected.\nIt treats repository content as data, not executable authority.\n\n## Non-goals\n\n- A Skill never grants capabilities by being installed or mentioned.\n- Agent definitions are not runtime JavaScript plugins.\n- Discovery does not recursively ingest every referenced file into context.\n\n## Core model\n\n`SkillLoader` validates roots, frontmatter, metadata, and progressively disclosed content. `SkillCatalog` merges\nthe Workspace `.qi/skills` scope with the user `~/.qi/skills` scope; a same-named Workspace Skill wins.\nAgent definitions are parsed declaratively. Shared frontmatter helpers enforce required fields without evaluating\nsource code. `version` is optional and projects as `unversioned` when absent.\n\n## Behavioral invariants\n\n- Missing or invalid frontmatter fails closed.\n- Skill roots that are symbolic links are rejected at the trust boundary.\n- Agent definition files are read as declarations and never executed.\n- Full resources remain unloaded until explicitly requested.\n- Installation copies a bounded allowlist of files through a sibling staging directory and atomic rename.\n- Installation never follows symbolic links, overwrites an existing Skill, or grants runtime capabilities.\n- Workspace updates require an exported ordinary-directory draft plus a fresh digest, and retain recovery state\n  when atomic publication cannot be confirmed.\n\n## Failure semantics\n\nInvalid roots, metadata, or definitions produce structured loader errors before content enters context. A load\nfailure does not fall back to executing or trusting the file.\n\n## Install and minimal use\n\n```sh\nnpm install @civaapple/qi-skills\n```\n\n```ts\nimport { parseFrontmatter } from \"@civaapple/qi-skills\";\n\nconst parsed = parseFrontmatter(\n  \"---\\nname: explain\\ndescription: Explain a repository\\n---\\nRead the smallest relevant files.\",\n  \"Example Skill\",\n);\n```\n\n## Public API\n\n`SkillLoader`, `SkillCatalog`, skill metadata/result types, agent definition types, and frontmatter parsing helpers.\n\n`SkillCatalog.install()` accepts an explicit local directory or a bare name found under configured compatibility\nroots such as `~/.codex/skills` (including `.system/<name>`). It has no implicit network registry. User scope is\nthe API default; callers must request Workspace scope explicitly.\n\n`exportWorkspaceDraft()` and `updateWorkspace()` are the create-draft/update pair for existing Workspace Skills.\nThey do not weaken the generic `.qi` file boundary; callers must still provide effect and path authority.\n\n## Change guide\n\nKeep discovery cheap and loading explicit. New metadata fields must define validation and whether they affect\nselection, context, or only presentation; none may imply authority.\n\n## Verification\n\n`tests/skills-agent.test.mjs` covers progressive disclosure, scope precedence, bounded local installation,\nfrontmatter, symlink roots, and non-execution.\n\n## Further reading\n\n- [Loading security](docs/loading-security.md)\n- [Skill and extension design](../../design/system-design.md#8-extensions-skills-mcp-codeact-graph-delegation-scheduling-and-introspection)\n","readmeFilename":"README.md"}