@sortedyuan/plugin-skills 0.0.0-stage → 0.2.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @sortedyuan/plugin-skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`createSkillsPlugin({ id?, create })` creates a `SkillSession` from the real
+`SkillRegistry` returned by `create(context)`. It provides `services.skills` and
+contributes the `skill_read` tool and dynamic instructions through the shared
+registries. Each Application has an independent activation state.
+Its instruction contribution uses `order: 0`. The initial catalog contains only
+names, descriptions and optional compatibility requirements; `skill_read` loads
+selected instructions and referenced resources progressively. Active documents
+remain available in subsequent instruction snapshots.
+Typed `config`, `configSchema`, dependency declarations, `requiresHooks`, and
+`version` follow [`PluginFactoryMetadata`](../../plugin-services/README.md).
+The factory owns its activation state declaration.
+
+Activated documents are restored before setup completes. Activations await
+`context.state.set()` before becoming visible, so Application persistence and state
+migration use the plugin host. Application also reads legacy `may.skills.active.v1`
+Session records when resuming existing data. New records use the versioned plugin
+state snapshot. Activating a skill retains its saved content across resume even
+when the original file changes.
+
+Closing the plugin removes its tool and instruction contributions. The registry is
+an immutable discovery snapshot with no resource disposal API.
+
+Tests discover, activate and restore actual `SKILL.md` files in the ignored
+`plugin-verification` directory: `pnpm --filter @sortedyuan/plugin-skills test`.

package/README.zh-CN.md

@@ -0,0 +1,20 @@
+# @sortedyuan/plugin-skills
+
+`createSkillsPlugin({ id?, create })` 使用 `create(context)` 返回的实际 `SkillRegistry`
+创建 `SkillSession`，提供 `services.skills`，并通过共享注册表贡献 `skill_read` 和动态指令。
+每个 Application 分别管理激活状态。
+指令贡献使用 `order: 0`。初始目录包含名称、描述及适用时的兼容要求；`skill_read`
+按需读取选定的指导和引用资源。已激活的文档持续出现在后续指令快照中。
+支持 [`PluginFactoryMetadata`](../../plugin-services/README.zh-CN.md) 中带类型的
+`config`、`configSchema`、依赖声明、`requiresHooks` 和 `version`。
+激活状态由工厂声明和管理。
+
+插件 setup 完成之前恢复激活文档，激活过程等待 `context.state.set()` 完成之后公开状态。
+Application 保存和状态迁移使用 PluginHost；恢复已有 Session 时也读取旧的
+`may.skills.active.v1` 记录。新的记录使用带版本的插件状态快照。
+恢复 Session 时保留已经激活的文档内容，即使原始文件已经改变。
+
+插件关闭时移除工具和指令贡献。SkillRegistry 是不可变的发现快照，没有资源关闭接口。
+
+测试在被忽略的 `plugin-verification` 目录中发现、激活和恢复实际 `SKILL.md` 文件。
+执行 `pnpm --filter @sortedyuan/plugin-skills test`。

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { type SkillRegistry } from "@sortedyuan/skills";
+import { type PluginDefinition, type PluginContext } from "@sortedyuan/plugin";
+import { type PluginFactoryMetadata } from "@sortedyuan/plugin-services";
+export interface SkillsPluginOptions<C = unknown> extends Omit<PluginFactoryMetadata<C>, "state"> {
+    readonly id?: string;
+    readonly create: (context: PluginContext<C>) => SkillRegistry | Promise<SkillRegistry>;
+}
+export declare function createSkillsPlugin<C = unknown>(options: SkillsPluginOptions<C>): PluginDefinition<C>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAgB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAA6B,KAAK,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAEpG,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC;IAC/F,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACxF;AACD,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAYpG"}

package/dist/index.js

@@ -0,0 +1,17 @@
+import { SkillSession } from "@sortedyuan/skills";
+import { definePlugin } from "@sortedyuan/plugin";
+import { services, factoryMetadata } from "@sortedyuan/plugin-services";
+export function createSkillsPlugin(options) {
+    return definePlugin({ ...factoryMetadata(options, [{ service: services.toolSources }, { service: services.instructionSources }]), id: options.id ?? "may.skills", provides: [services.skills],
+        state: { version: 1, initial: [] }, async setup(context) {
+            const skills = new SkillSession(await options.create(context));
+            skills.restore(context.state.get());
+            skills.setSink((documents) => context.state.set(documents));
+            context.provide(services.skills, skills);
+            const registration = { id: context.pluginId, pluginOrder: context.pluginOrder };
+            context.defer(context.get(services.toolSources).add(() => [skills.readTool()], registration));
+            context.defer(context.get(services.instructionSources).add(() => skills.instructions(), { ...registration, order: 0 }));
+        },
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,YAAY,EAA6C,MAAM,oBAAoB,CAAC;AAC7F,OAAO,EAAE,QAAQ,EAAE,eAAe,EAA8B,MAAM,6BAA6B,CAAC;AAMpG,MAAM,UAAU,kBAAkB,CAAc,OAA+B;IAC7E,OAAO,YAAY,CAAC,EAAE,GAAG,eAAe,CAAC,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,kBAAkB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,YAAY,EAAE,QAAQ,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC3L,KAAK,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO;YACrD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YAC/D,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACpC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC;YAC5D,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACzC,MAAM,YAAY,GAAG,EAAE,EAAE,EAAE,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;YAChF,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;YAC9F,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,EAAE,GAAG,YAAY,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC1H,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@sortedyuan/plugin-skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.3",
+  "description": "Session skill state, instructions and tool plugin factory.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@sortedyuan/skills": "0.2.0",
+    "@sortedyuan/plugin": "0.2.0",
+    "@sortedyuan/plugin-services": "0.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "test:coverage": "pnpm run build && node --test --experimental-test-coverage test/*.test.mjs"
+  }
 }