@qilin-agent/tool-skill 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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.i18n.yaml

@@ -0,0 +1,136 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/skill/tool-skill/README.md
+/:
+  en: e1bb629bc25d7d51
+  zh: 0018e221e28ddcff
+/qilin-tool-skill:
+  en: c0e7b6c680d7e631
+  zh: c482d0246bdb576d
+/qilin-tool-skill/summary:
+  en: 399399741476179c
+  zh: 074ec6657481d320
+/qilin-tool-skill/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-tool-skill/use-this-package:
+  en: 5c21d1ba71c1c3e1
+  zh: 3e2505d4625b57b4
+/qilin-tool-skill/use-this-package/when-to-choose-it:
+  en: b7d33bd969826ee3
+  zh: 4e155a0f14b41541
+/qilin-tool-skill/use-this-package/mount-and-configure:
+  en: 16b55a6bcff86e62
+  zh: 4cfc947f684bde99
+/qilin-tool-skill/use-this-package/what-the-model-gets:
+  en: cf02796bd3f8877e
+  zh: 81b93b1eb7f74690
+/qilin-tool-skill/use-this-package/observable-success-and-failures:
+  en: 813f1a7ab04d283e
+  zh: 4adfcffcbb131d54
+/qilin-tool-skill/understand-the-implementation:
+  en: 1aa627255c35178f
+  zh: 44d8633ea56765d3
+/qilin-tool-skill/understand-the-implementation/design-concept:
+  en: a1a90d97c05bf124
+  zh: 80c5d2a05c2168dc
+/qilin-tool-skill/understand-the-implementation/source-map:
+  en: 509699e3a467df41
+  zh: ff7fc30ec4998e5a
+/qilin-tool-skill/understand-the-implementation/catalog-lifecycle:
+  en: 847745cf78860904
+  zh: 55137ebef224ad48
+/qilin-tool-skill/understand-the-implementation/invocation-boundary:
+  en: bb8543ea29cbc451
+  zh: b1124fa489bf9ea4
+/qilin-tool-skill/further-exploration:
+  en: 9dd0a826481d5903
+  zh: dcd1c4a40518eb7d
+/qilin-tool-skill/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-tool-skill/model-experience/session-catalog:
+  en: ed929c61dd301a56
+  zh: 376c8d69b6fa7df6
+/qilin-tool-skill/model-experience/session-catalog/what-the-model-sees:
+  en: 8d2a9b439fad4c1b
+  zh: 4a64df685a06cbec
+/qilin-tool-skill/model-experience/session-catalog/what-the-model-sees/skill-catalog-template:
+  en: 8ca9241e26124ce3
+  zh: d083f87eaae40e15
+/qilin-tool-skill/model-experience/session-catalog/token-effect:
+  en: c05d3d46e5139c4d
+  zh: 8acfa475cddaeb18
+/qilin-tool-skill/model-experience/session-catalog/kv-cache-effect:
+  en: e6e6758c96527e19
+  zh: 8f95e36da658c95a
+/qilin-tool-skill/model-experience/tool-schema:
+  en: e4c7376d4f29dbd5
+  zh: 6b7a9eaf69c9ea53
+/qilin-tool-skill/model-experience/tool-schema/what-the-model-sees:
+  en: b473819ceed489b1
+  zh: 169aef7191ee94da
+/qilin-tool-skill/model-experience/tool-schema/token-effect:
+  en: 4a8881f7a361cb7f
+  zh: cba76f0578a36953
+/qilin-tool-skill/model-experience/tool-schema/kv-cache-effect:
+  en: 77f9b9513ed7692d
+  zh: 249f6b975a2db718
+/qilin-tool-skill/model-experience/tool-result:
+  en: f8ffc2b983f05ffc
+  zh: 8573891441963be4
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees:
+  en: a1bc95abf3a7493c
+  zh: e3d200040493c0a7
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees/skill-result-template:
+  en: 66220f8d7628e5cc
+  zh: d8469e173485a5ca
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees/provider-managed-resource-guidance:
+  en: 80107e79cb15b0d0
+  zh: c53f14bb87aa8395
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees/directory-resource-guidance:
+  en: 9a060c44c0d00e06
+  zh: 13ccf1d8b8e3d865
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees/url-resource-guidance:
+  en: 6f4bc625155f73e3
+  zh: 4bc8641df028caed
+/qilin-tool-skill/model-experience/tool-result/what-the-model-sees/opaque-resource-guidance:
+  en: 958b9c46d9785397
+  zh: 34f053e4ab8296c2
+/qilin-tool-skill/model-experience/tool-result/token-effect:
+  en: 8604cca6caa413a0
+  zh: 1b0412b8008e76c8
+/qilin-tool-skill/model-experience/tool-result/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: bee82b41983a66a0
+/qilin-tool-skill/model-experience/tool-errors:
+  en: 2d4f2c8605eccab3
+  zh: 67f1f0218f73c6bf
+/qilin-tool-skill/model-experience/tool-errors/what-the-model-sees:
+  en: 3e70742d93164968
+  zh: 63fd2159c9cc5c8c
+/qilin-tool-skill/model-experience/tool-errors/token-effect:
+  en: 681cadd5be7b8ac1
+  zh: 5e169acfd30b2931
+/qilin-tool-skill/model-experience/tool-errors/kv-cache-effect:
+  en: f5d5f97a153f7c70
+  zh: bee82b41983a66a0
+/qilin-tool-skill/model-experience/user-explicit-invocation-injection:
+  en: 657124bac34aba61
+  zh: 00aae3514ab12676
+/qilin-tool-skill/model-experience/user-explicit-invocation-injection/what-the-model-sees:
+  en: f9c7b7c6cb042d2f
+  zh: ba3372515505f413
+/qilin-tool-skill/model-experience/user-explicit-invocation-injection/token-effect:
+  en: d1068ea431fb768f
+  zh: acacd161731c27c6
+/qilin-tool-skill/model-experience/user-explicit-invocation-injection/kv-cache-effect:
+  en: 127c0139472bfaab
+  zh: 805dc2f730c47f40
+/qilin-tool-skill/known-limitations-and-deferred-work:
+  en: 6017a1dc04618288
+  zh: d613164f0e9258f9
+/qilin-tool-skill/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,257 @@
-# Temporary Holding Version
+---
+description: "The model-facing skill catalog and loader tool for users and maintainers understanding what agents see, or configuring the session skill catalog."
+kind: "package-reference"
+---
 
-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.
+# @qilin-agent/tool-skill
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Agents can discover and load skills during a session. Before the first request, when model-invocable skills exist and the `skill` tool is visible, they receive a durable catalog of available skill names and capped descriptions, and can use the `skill` tool to load full instructions. Users can invoke a user-invocable skill with `/name`, which injects the same instructions into that step. Catalog changes append a complete replacement, including an empty catalog that retires old names; configure `catalogDescriptionMaxLength` to limit each description.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the plugin alongside the skill registry to give agents a session skill catalog and the `skill` loader tool. It requires `ctx.agents`, `ctx.tools`, and `ctx.skills`.
+
+### When to choose it
+
+Use it when agents should discover and load skills during a session. Skip it when skill loading is handled by another consumer or not needed at all — without it, providers and the registry still work, but nothing renders a catalog or a tool for the model.
+
+### Mount and configure
+
+Load the plugin together with the skill registry and at least one provider. The only configuration caps the normalized description length rendered in the catalog.
+
+```yaml
+- name: '@qilin-agent/skill'
+- name: '@qilin-agent/skill-filesystem'
+- name: '@qilin-agent/tool-skill'
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `catalogDescriptionMaxLength` | `500` | Maximum normalized description length rendered in the session catalog; minimum 3 |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#qilin-agenttool-skill) is the exhaustive source for every accepted field.
+
+### What the model gets
+
+- **A session catalog.** When model-invocable skills exist and the `skill` tool is visible, the agent receives a durable user-role message before its first request, listing each skill's name and a capped description; the message tells the model to load a skill with the tool before acting on it, and never to infer instructions from the summary alone.
+- **A loader tool.** The model calls `skill` with the exact skill name and receives the full instruction body plus resource guidance in a canonical `<skill_content>` block; the result is retained as ordinary tool history.
+- **Explicit user invocation.** A `/name` token in direct user input that names a user-invocable skill injects that skill's instructions into the step, without the model having to load it.
+- **Live catalog updates.** Later membership, description, or visibility changes append a complete replacement catalog; removing every skill appends an empty catalog that retires older names.
+
+### Observable success and failures
+
+Loading a listed skill returns its full instructions; the model sees one canonical shape whether the load came from the tool or from a user's explicit invocation. An invalid name reports `Error: invalid skill name "<name>"`, an unknown name reports the skill is unknown or no longer available, and a skill disabled for model invocation reports it is not available for model invocation. The catalog is omitted entirely when no catalog was ever published and either no model-invocable skills exist or the `skill` tool is hidden or shadowed; after a catalog has been published, either visibility loss — the `skill` tool hidden or shadowed by a same-name scoped tool — or removal of every skill instead appends an empty catalog that retires older names.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the catalog and the invocation boundary are built; the observable behavior is fully covered in [Use this package](#use-this-package) and the Model Experience section below.
+
+### Design concept
+
+The package is built on two ideas. First, the catalog is a durable projection, diffed by a digest over the published entries rather than the rendered prose, so the `<system-reminder>` framing can never force a republish and consumers never re-parse the `<available_skills>` block. Second, one canonical rendering serves both load paths — the tool result and the user-explicit injection — through `renderSkillContent` shared from `qilin-skill`, so the model sees the same `<skill_content>` shape regardless of who initiated the load.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: tool registration, catalog and gesture pre-step listeners, rendering and digest |
+
+### Catalog lifecycle
+
+At each eligible `agent/pre-step`, the plugin snapshots the calling session's skill catalog, applies exact `skill` tool visibility, filters to model-invocable skills, and compares a digest of the entries against the newest visible `skill-catalog` message in the session log. When the digest changed, it hands the `enter` decision a durable user-role message containing the complete replacement catalog; an empty replacement explicitly retires earlier names. An incomplete provider snapshot emits nothing and preserves the last-good view for the next pre-step. The visibility check compares against the exact tool definition this plugin registered, so a scoped same-name shadow removes both the schema and its guidance; the plugin works mounted globally or inside one agent's composition.
+
+### Invocation boundary
+
+The `/name` gesture listener scans only claimed user messages: a whitespace-bounded token naming a user-invocable skill in the workspace catalog injects the same `<skill_content>` rendering as a `user`-role instructions context appended after every other injection. Unknown names and user-disabled skills stay ordinary prose. This is the only entry point for `disable-model-invocation` skills, which the catalog and the `skill` tool never expose.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the registry vocabulary behind the catalog to the exact tool schema and the design rationale.
+
+- [Skill subsystem reference](../../../docs/subsystems/skills.md) — the registry and provider vocabulary behind the catalog.
+- [skill package](../skill/README.md) — the registry and the shared `renderSkillContent` rendering.
+- [Generated tool catalog](../../../docs/tool-catalog.md#qilin-agenttool-skill) — the exact `skill` schema the model receives.
+- [User-explicit skill invocation Agent Note](../../../.agents/notes/archived/feature/2026-08-08-user-explicit-skill-invocation.md) — the `/name` gesture design.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Session catalog
+
+#### What the model sees
+
+If model-invocable skills exist and this exact `skill` tool is visible, the agent receives the catalog template below as a durable user-role message before the first request, with one data-dependent entry per sorted skill. Later membership, description, or visibility changes append a complete replacement using the same `<available_skills>` envelope; deleting every skill appends an empty envelope with an explicit instruction not to use older names. The template's closing sentence is the rule against double-loading: the user-explicit gesture boundary (the pre-step listener below) injects the same `renderSkillContent` output (shared from `@qilin-agent/skill`) inline, and the catalog tells the model to follow that block instead of re-loading the skill through the tool; the replacement-catalog template carries the same anti-double-loading rule in both arms, including the emptied catalog.
+
+##### Skill catalog template
+
+```markdown
+<system-reminder>
+A skill is a reusable set of task-specific instructions. The following skills are available in this session:
+
+<available_skills>
+- `<name>`: <normalized-and-capped-description>
+</available_skills>
+
+If the user names a skill, or the task clearly matches a skill's description, call the `skill` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the `skill` tool again for that skill.
+</system-reminder>
+```
+
+#### Token effect
+
+Repeated input cost scales with skill count and `catalogDescriptionMaxLength`; no initial catalog tokens are sent when the list is empty or the tool is hidden or shadowed. Each actual catalog change adds one retained complete replacement message.
+
+#### KV Cache effect
+
+The initial durable catalog is appended after the existing reusable prefix. Dynamic changes are append-only history after that catalog, so earlier reusable tokens stay intact while each newly appended catalog and later turns form a new suffix. A new or resumed instance with a changed digest may affect cache reuse from the newly appended catalog position.
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`skill` schema](../../../docs/tool-catalog.md#qilin-agenttool-skill).
+
+#### Token effect
+
+Fixed schema cost per request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the tool definition and visibility are unchanged. Shadowing, restrictions, or plugin lifecycle changes may invalidate reuse from this schema.
+
+### Tool result
+
+#### What the model sees
+
+A successful call uses the result template and the provider-managed, directory, URL, or opaque resource guidance below.
+
+##### Skill result template
+
+```markdown
+<skill_content name="<escaped-name>">
+<skill_resources>
+<resource-guidance>
+</skill_resources>
+
+<skill_instructions>
+<provider-owned-instruction-body>
+</skill_instructions>
+</skill_content>
+```
+
+##### Provider-managed resource guidance
+
+```markdown
+Resources for this skill are managed by provider "<provider>".
+Load referenced resources only as needed.
+```
+
+##### Directory resource guidance
+
+```markdown
+Base directory for this skill: <path>
+Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
+```
+
+##### URL resource guidance
+
+```markdown
+Base URL for this skill: <url>
+Resolve relative URLs mentioned by this skill against the base URL before using them. Load referenced resources only as needed.
+```
+
+##### Opaque resource guidance
+
+```markdown
+Resources for this skill: <description>
+Load referenced resources only as needed.
+```
+
+#### Token effect
+
+Loaded instructions are data-dependent tool-result tokens, resent on later steps until compaction; no duplicate `agent.inject()` copy is made.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Tool errors
+
+#### What the model sees
+
+Invalid or stale selections return exactly `Error: invalid skill name "<name>"`, `Error: skill "<name>" is unknown or no longer available`, or `Error: skill "<name>" is not available for model invocation`. Provider-thrown lookup text is data-dependent and receives the same `Error: <message>` wrapper.
+
+#### Token effect
+
+Only a failing call adds these retained tokens.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### User-explicit invocation injection
+
+#### What the model sees
+
+A whitespace-bounded `/name` token anywhere in a claimed user message, naming a user-invocable skill in the workspace catalog, injects that skill's full `<skill_content>` rendering (the exact result-template shape above) as a `user`-role instructions context appended after every other injection of that step — background first, the material to act on last. Only direct user input is scanned, the check runs on the loaded definition, and unknown or user-disabled names stay ordinary prose. This is the sole entry point for `disable-model-invocation` skills, which the catalog and the `skill` tool never expose; the catalog's closing sentence tells the model to follow the injected block instead of re-loading it.
+
+#### Token effect
+
+Each gesture adds one rendered skill body to that turn as injected context — the same size as the tool result for the same skill, paid deterministically at the user's request instead of at the model's discretion. Repeated gestures for one skill within one step inject once.
+
+#### KV Cache effect
+
+Append-only; the injection lands after the reusable request prefix inside the step's message batch and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the catalog or the loader is a poor fit. They are current package constraints, not a task backlog.
+
+- **The catalog omits `whenToUse`, source, and provider metadata** — routing is based only on name and a capped description; `whenToUse` remains provider metadata and is not rendered by the loaded wrapper either.
+- **Loaded instruction bodies have no size cap** — a provider can return a skill large enough to consume substantial next-step context; only catalog descriptions are truncated.
+- **Resources are guidance, not attachments** — the tool reports a base directory/URL/opaque hint but neither enumerates nor fetches referenced files for the model.
+- **Loading is one-shot text** — there is no partial, streaming, or cached-content handle when a remote provider is slow or a skill body is large.
+- **Catalog replacement is whole-list** — one changed name or description appends every visible summary; this keeps stale-name retirement explicit but costs tokens proportional to the catalog.
+- **Bodies are not versioned** — body-only edits do not change the catalog digest or notify the model; a later tool call reads the current provider content while earlier tool results remain historical facts.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>