pi-skill-shiori 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/Docs/recommendation-surface.md +15 -0
- package/Docs/usage.md +164 -0
- package/README.md +62 -282
- package/ROADMAP.md +1 -1
- package/package.json +1 -1
- package/src/retrieval-expanded.ts +12 -3
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,24 @@ All notable changes to this project will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
This project follows semantic versioning.
|
|
6
6
|
|
|
7
|
+
## [0.6.2] - 2026-07-02
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- Expanded retrieval (`retrieveCandidatesExpanded`) now preserves `[trigger]` badges when query variants also score the skill higher via description tokens.
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- `Docs/recommendation-surface.md` documents the dogfood review outcome and recommendation to keep badges on default surfaces.
|
|
16
|
+
|
|
17
|
+
## [0.6.1] - 2026-07-01
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- README aligned with Pi OSS minimal-docs policy: badges, required entrypoint sections, Quick start, Package contents, Links.
|
|
22
|
+
- Detailed configuration and operational notes moved to `Docs/usage.md`.
|
|
23
|
+
- README install examples and status text updated to match package version `0.6.1`.
|
|
24
|
+
|
|
7
25
|
## [0.6.0] - 2026-06-29
|
|
8
26
|
|
|
9
27
|
### Added
|
|
@@ -60,3 +60,18 @@ Always-visible skills may still appear as recommendations when they match a task
|
|
|
60
60
|
`/shiori:stats` recommendation feedback records offers, loads, and follow-through by source (`auto-inject`, `command`, `tool`). Metrics do **not** store reason badges or per-reason tallies.
|
|
61
61
|
|
|
62
62
|
Use badges to understand individual suggestions during a session. Use metrics to see whether recommendations are being loaded after they are offered.
|
|
63
|
+
|
|
64
|
+
## Dogfood review (0.6.2)
|
|
65
|
+
|
|
66
|
+
Reviewed the badge rollout across `/shiori:recommend` review mode, auto-inject candidate blocks, and `shiori_recommend` collapsed output using realistic skill policies and natural-language tasks (`browser scraping screenshot`, `auth login`, `vault search markdown`).
|
|
67
|
+
|
|
68
|
+
### Findings
|
|
69
|
+
|
|
70
|
+
- **Trust:** Compact badges clarify *why* a skill surfaced when they match the retrieval path. Users can distinguish policy trigger hits from description token matches without reading long `Why:` lines.
|
|
71
|
+
- **Noise:** The three-label vocabulary stays short enough for picker labels and tool summaries. No extra badge is shown when retrieval cannot classify a match.
|
|
72
|
+
- **Friction fixed:** Expanded retrieval (`buildRetrievalQueries`) evaluates per-token variants. A description-only variant could outscore a trigger match and incorrectly replace `[trigger]` with `[description]`. Merge logic now keeps trigger classification when any variant fired a policy trigger.
|
|
73
|
+
- **Deferred:** Broader recommendation-model changes (new badge types, per-reason metrics, confidence scores in default surfaces) stay out of scope.
|
|
74
|
+
|
|
75
|
+
### Recommendation
|
|
76
|
+
|
|
77
|
+
Keep reason badges on the default recommendation surfaces. Treat `[trigger]` as the authoritative label whenever policy triggers matched, even if expanded queries also score the description highly.
|
package/Docs/usage.md
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Usage
|
|
2
|
+
|
|
3
|
+
Detailed configuration and operational notes for Pi Skill Shiori. For install and quick start, see [README](../README.md).
|
|
4
|
+
|
|
5
|
+
## Requirements
|
|
6
|
+
|
|
7
|
+
- Pi Coding Agent with package support
|
|
8
|
+
- Node.js `>=22.5`
|
|
9
|
+
- `npm`
|
|
10
|
+
|
|
11
|
+
Pi core packages are peer dependencies and should be supplied by the Pi runtime:
|
|
12
|
+
|
|
13
|
+
- `@earendil-works/pi-ai`
|
|
14
|
+
- `@earendil-works/pi-coding-agent`
|
|
15
|
+
- `@earendil-works/pi-tui`
|
|
16
|
+
- `typebox`
|
|
17
|
+
|
|
18
|
+
## Vault-wide skill inventory
|
|
19
|
+
|
|
20
|
+
Shiori builds a searchable inventory from these roots (in discovery order; first match wins on duplicate skill names):
|
|
21
|
+
|
|
22
|
+
| Root | Scope |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `<cwd>/.pi/skills` | Project-local Pi skills |
|
|
25
|
+
| `<cwd>/.agents/skills` | Project-local Agent skills |
|
|
26
|
+
| `~/.pi/agent/skills` | User-global Pi agent skills |
|
|
27
|
+
| `inventory.roots` entries | Optional extra roots (relative to `<cwd>` or absolute) |
|
|
28
|
+
|
|
29
|
+
Refresh behavior:
|
|
30
|
+
|
|
31
|
+
- **Session start** builds the initial inventory and SQLite FTS index.
|
|
32
|
+
- **Auto-refresh** (default) rescans roots before retrieval when any `SKILL.md` path changes. This is a directory walk only; it rebuilds the FTS index when the fingerprint changes.
|
|
33
|
+
- **Manual refresh** via `/shiori:reload` always rebuilds the inventory and FTS index immediately.
|
|
34
|
+
- Disable auto-refresh when you prefer a fixed snapshot:
|
|
35
|
+
|
|
36
|
+
```yaml
|
|
37
|
+
inventory:
|
|
38
|
+
autoRefreshOnChange: false
|
|
39
|
+
roots:
|
|
40
|
+
- custom-skills
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Cost/latency trade-offs:
|
|
44
|
+
|
|
45
|
+
- Auto-refresh adds a shallow filesystem walk on each agent turn while enabled. It avoids stale search results after local skill edits without restarting Pi.
|
|
46
|
+
- A full refresh rebuilds the SQLite FTS database and scales with total indexed skills and description length. Large vaults with many roots may prefer `autoRefreshOnChange: false` plus explicit `/shiori:reload` after bulk imports.
|
|
47
|
+
- Search stays description-first and policy-aware: only `triggerable` skills become candidates, with FTS ranking over names, descriptions, and policy triggers.
|
|
48
|
+
|
|
49
|
+
## Configure
|
|
50
|
+
|
|
51
|
+
Create `.pi/skill-shiori.yml` in the project where Pi runs.
|
|
52
|
+
|
|
53
|
+
Minimal config:
|
|
54
|
+
|
|
55
|
+
```yaml
|
|
56
|
+
zeroCatalog:
|
|
57
|
+
enabled: true
|
|
58
|
+
|
|
59
|
+
defaults:
|
|
60
|
+
activation: explicit
|
|
61
|
+
|
|
62
|
+
candidateInjection:
|
|
63
|
+
maxCandidates: 3
|
|
64
|
+
minScore: 0.62
|
|
65
|
+
|
|
66
|
+
alwaysVisible:
|
|
67
|
+
- pi-skill-shiori
|
|
68
|
+
|
|
69
|
+
skills:
|
|
70
|
+
reddit-research:
|
|
71
|
+
activation: triggerable
|
|
72
|
+
triggers:
|
|
73
|
+
include:
|
|
74
|
+
- Reddit
|
|
75
|
+
- Redditで調べて
|
|
76
|
+
- reputation on Reddit
|
|
77
|
+
exclude: []
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Policy rules:
|
|
81
|
+
|
|
82
|
+
- `defaults.activation: explicit` is the safe default. Unlisted skills are not auto-candidates.
|
|
83
|
+
- `activation: triggerable` allows Shiori to recommend the skill for matching requests.
|
|
84
|
+
- `alwaysVisible` lists skills that should remain visible in the Skill Catalog during Zero-Catalog Mode. Use this for a tiny safety-critical allowlist instead of broad trigger rules.
|
|
85
|
+
- Missing `alwaysVisible` entries are reported by `/shiori:doctor` and warned once per session when Zero-Catalog Mode runs.
|
|
86
|
+
- `candidateInjection.maxCandidates` limits how many suggestions enter the prompt.
|
|
87
|
+
- `candidateInjection.minScore` drops weak matches.
|
|
88
|
+
|
|
89
|
+
Generate a starter policy from discovered skills:
|
|
90
|
+
|
|
91
|
+
```text
|
|
92
|
+
/shiori:bootstrap
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
This writes a generated review file next to `.pi/skill-shiori.yml`. Review it before using it as your real policy.
|
|
96
|
+
|
|
97
|
+
## Suppression statuses
|
|
98
|
+
|
|
99
|
+
`/shiori:doctor` reports the last suppression result:
|
|
100
|
+
|
|
101
|
+
| Status | Meaning |
|
|
102
|
+
|---|---|
|
|
103
|
+
| `disabled` | `zeroCatalog.enabled` is false. |
|
|
104
|
+
| `not-needed` | No normal Skill Catalog marker was present in that turn's prompt, so nothing needed deletion. |
|
|
105
|
+
| `suppressed` | Shiori recognized and removed the normal Skill Catalog for that turn. |
|
|
106
|
+
| `failed-pattern-not-found` | A catalog-like marker existed, but Shiori could not safely identify its boundary. Prompt left unchanged. |
|
|
107
|
+
|
|
108
|
+
`not-needed` is not an error. It often means Pi or another configuration already avoided injecting the normal catalog.
|
|
109
|
+
|
|
110
|
+
## Retrieval backend
|
|
111
|
+
|
|
112
|
+
Shiori prefers `sqlite-fts` using Node's built-in `node:sqlite` and FTS5. If that is unavailable, it falls back to `token-match`.
|
|
113
|
+
|
|
114
|
+
Check backend:
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
/shiori:doctor
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Example:
|
|
121
|
+
|
|
122
|
+
```text
|
|
123
|
+
retrievalBackend: sqlite-fts
|
|
124
|
+
code: prompt-boundary-v3
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Recommendation feedback metrics
|
|
128
|
+
|
|
129
|
+
`/shiori:stats` includes session-local recommendation feedback so operators can tune trigger rules from real outcomes instead of guesswork.
|
|
130
|
+
|
|
131
|
+
Recorded (bounded, in-memory for the current Pi session):
|
|
132
|
+
|
|
133
|
+
- recommendation offers and candidate slot counts per source (`auto-inject`, `command`, `tool`)
|
|
134
|
+
- load follow-through when recommended skills are pre-loaded or later loaded via `shiori_load_skill`
|
|
135
|
+
- abandoned recommendation flows (candidates shown but not loaded, e.g. review-only mode)
|
|
136
|
+
- zero-candidate queries (obvious misses)
|
|
137
|
+
- per-skill offered/loaded tallies (up to 50 skill names, oldest entries dropped first)
|
|
138
|
+
|
|
139
|
+
Not recorded:
|
|
140
|
+
|
|
141
|
+
- user prompts, task descriptions, or transcript bodies
|
|
142
|
+
- skill `SKILL.md` contents
|
|
143
|
+
- filesystem paths beyond skill names already visible in policy/inventory
|
|
144
|
+
|
|
145
|
+
Retention boundary:
|
|
146
|
+
|
|
147
|
+
- counters reset when the Pi session ends
|
|
148
|
+
- no disk persistence or cross-session analytics in this slice
|
|
149
|
+
- inspect the compact summary at the top of `/shiori:stats`, with full JSON below
|
|
150
|
+
|
|
151
|
+
Example summary line:
|
|
152
|
+
|
|
153
|
+
```text
|
|
154
|
+
Recommendation feedback (session-local, no prompts stored)
|
|
155
|
+
offers: 4 | candidate slots: 7 | loaded: 3
|
|
156
|
+
abandoned: 1 | zero-candidate queries: 2 | follow-through: 42.9%
|
|
157
|
+
auto-inject: offers=2, loaded=1, zeroHits=1
|
|
158
|
+
command: offers=1, loaded=2, zeroHits=1
|
|
159
|
+
top skills: auth-helper(1/2), deploy-kit(1/1)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Related docs
|
|
163
|
+
|
|
164
|
+
- [Recommendation surface](recommendation-surface.md) — reason badges, Always Visible policy, and metrics interplay
|
package/README.md
CHANGED
|
@@ -1,46 +1,40 @@
|
|
|
1
1
|
# Pi Skill Shiori
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/eiei114/pi-skill-shiori/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/eiei114/pi-skill-shiori/actions/workflows/publish.yml)
|
|
5
|
+
[](https://www.npmjs.com/package/pi-skill-shiori)
|
|
6
|
+
[](https://www.npmjs.com/package/pi-skill-shiori)
|
|
7
|
+
[](https://github.com/eiei114/pi-skill-shiori/blob/main/LICENSE)
|
|
8
|
+
|
|
9
|
+
[](https://docs.npmjs.com/generating-provenance-statements)
|
|
4
10
|
|
|
5
|
-
|
|
11
|
+
> Pi extension that keeps large Agent Skill catalogs out of the model prompt and loads only the skills that match the current task.
|
|
6
12
|
|
|
7
13
|
For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
|
|
8
14
|
|
|
9
|
-
## What
|
|
15
|
+
## What this is
|
|
10
16
|
|
|
11
|
-
|
|
12
|
-
- **Policy-based retrieval**: treats skills as explicit by default and only candidates skills marked as triggerable.
|
|
13
|
-
- **Compact candidate injection**: injects short skill suggestions instead of full `SKILL.md` files.
|
|
14
|
-
- **On-demand loading**: exposes `shiori_load_skill` so the model can load one selected skill body when needed.
|
|
15
|
-
- **Vault-wide skill inventory**: indexes skills from project and user-global roots, with optional extra roots in policy.
|
|
16
|
-
- **SQLite FTS retrieval**: indexes skill names, descriptions, and policy triggers with `node:sqlite` + FTS5, with token-match fallback.
|
|
17
|
-
- **Compact UI output**: keeps skill-load logs short while still passing full skill text to the model.
|
|
17
|
+
Pi Skill Shiori is a [Pi](https://pi.dev/) package for vaults or projects with many Agent Skills where the default catalog becomes noisy and expensive. It hides the normal skill catalog when safe, recommends triggerable skills with compact summaries, and loads full `SKILL.md` bodies on demand.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
`0.6.1` is an early working release. Prompt-boundary suppression is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
## Features
|
|
22
22
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
- `@earendil-works/pi-ai`
|
|
32
|
-
- `@earendil-works/pi-coding-agent`
|
|
33
|
-
- `@earendil-works/pi-tui`
|
|
34
|
-
- `typebox`
|
|
23
|
+
- **Zero-Catalog Mode** — hides the normal skill catalog when Pi exposes one in the system prompt.
|
|
24
|
+
- **Policy-based retrieval** — treats skills as explicit by default and only candidates skills marked as triggerable.
|
|
25
|
+
- **Compact candidate injection** — injects short skill suggestions instead of full `SKILL.md` files.
|
|
26
|
+
- **On-demand loading** — exposes `shiori_load_skill` so the model can load one selected skill body when needed.
|
|
27
|
+
- **Vault-wide skill inventory** — indexes skills from project and user-global roots, with optional extra roots in policy.
|
|
28
|
+
- **SQLite FTS retrieval** — indexes skill names, descriptions, and policy triggers with `node:sqlite` + FTS5, with token-match fallback.
|
|
29
|
+
- **Recommendation reason badges** — compact `[trigger]`, `[description]`, and `[low match]` labels on surfaced skills.
|
|
30
|
+
- **Session-local feedback metrics** — `/shiori:stats` tracks offers, loads, and follow-through without storing prompts.
|
|
35
31
|
|
|
36
32
|
## Install
|
|
37
33
|
|
|
38
34
|
### Global install from npm
|
|
39
35
|
|
|
40
|
-
After the package is published to npm:
|
|
41
|
-
|
|
42
36
|
```bash
|
|
43
|
-
pi install npm:pi-skill-shiori@0.
|
|
37
|
+
pi install npm:pi-skill-shiori@0.6.1
|
|
44
38
|
```
|
|
45
39
|
|
|
46
40
|
Without a version pin:
|
|
@@ -51,10 +45,8 @@ pi install npm:pi-skill-shiori
|
|
|
51
45
|
|
|
52
46
|
### Project-local install from npm
|
|
53
47
|
|
|
54
|
-
Use `-l` to write the package to the current project’s `.pi/settings.json`:
|
|
55
|
-
|
|
56
48
|
```bash
|
|
57
|
-
pi install -l npm:pi-skill-shiori@0.
|
|
49
|
+
pi install -l npm:pi-skill-shiori@0.6.1
|
|
58
50
|
```
|
|
59
51
|
|
|
60
52
|
Without a version pin:
|
|
@@ -63,47 +55,10 @@ Without a version pin:
|
|
|
63
55
|
pi install -l npm:pi-skill-shiori
|
|
64
56
|
```
|
|
65
57
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
```json
|
|
69
|
-
{
|
|
70
|
-
"packages": [
|
|
71
|
-
"npm:pi-skill-shiori@0.5.0"
|
|
72
|
-
]
|
|
73
|
-
}
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
Equivalent unpinned manual `.pi/settings.json` entry:
|
|
77
|
-
|
|
78
|
-
```json
|
|
79
|
-
{
|
|
80
|
-
"packages": [
|
|
81
|
-
"npm:pi-skill-shiori"
|
|
82
|
-
]
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
### Global install from GitHub
|
|
87
|
-
|
|
88
|
-
```bash
|
|
89
|
-
pi install git:github.com/eiei114/pi-skill-shiori@v0.5.0
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Without a tag pin:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
pi install git:github.com/eiei114/pi-skill-shiori
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
### Project-local install from GitHub
|
|
99
|
-
|
|
100
|
-
```bash
|
|
101
|
-
pi install -l git:github.com/eiei114/pi-skill-shiori@v0.5.0
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
Without a tag pin:
|
|
58
|
+
### Install from GitHub
|
|
105
59
|
|
|
106
60
|
```bash
|
|
61
|
+
pi install git:github.com/eiei114/pi-skill-shiori@v0.6.1
|
|
107
62
|
pi install -l git:github.com/eiei114/pi-skill-shiori
|
|
108
63
|
```
|
|
109
64
|
|
|
@@ -116,114 +71,29 @@ pi -e git:github.com/eiei114/pi-skill-shiori
|
|
|
116
71
|
|
|
117
72
|
### Local development install
|
|
118
73
|
|
|
119
|
-
From a project that should use your checkout:
|
|
120
|
-
|
|
121
74
|
```bash
|
|
122
75
|
pi install -l /absolute/path/to/pi-skill-shiori
|
|
123
76
|
```
|
|
124
77
|
|
|
125
|
-
|
|
78
|
+
## Quick start
|
|
126
79
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
}
|
|
133
|
-
```
|
|
80
|
+
1. Install the package (see [Install](#install)).
|
|
81
|
+
2. Create `.pi/skill-shiori.yml` in your Pi project (see [Docs/usage.md](Docs/usage.md#configure)).
|
|
82
|
+
3. Start Pi and run `/shiori:doctor` to confirm policy path, indexed roots, and suppression status.
|
|
83
|
+
4. Use `/shiori:bootstrap` to draft a policy from discovered skills, then `/shiori:reload` after edits.
|
|
84
|
+
5. Ask the agent for help; Shiori injects compact candidates or use `/shiori:recommend` for an interactive flow.
|
|
134
85
|
|
|
135
|
-
|
|
86
|
+
Commands take no inline arguments. Details are collected after launch via Pi UI prompts.
|
|
136
87
|
|
|
137
|
-
##
|
|
138
|
-
|
|
139
|
-
Shiori builds a searchable inventory from these roots (in discovery order; first match wins on duplicate skill names):
|
|
140
|
-
|
|
141
|
-
| Root | Scope |
|
|
142
|
-
|---|---|
|
|
143
|
-
| `<cwd>/.pi/skills` | Project-local Pi skills |
|
|
144
|
-
| `<cwd>/.agents/skills` | Project-local Agent skills |
|
|
145
|
-
| `~/.pi/agent/skills` | User-global Pi agent skills |
|
|
146
|
-
| `inventory.roots` entries | Optional extra roots (relative to `<cwd>` or absolute) |
|
|
147
|
-
|
|
148
|
-
Refresh behavior:
|
|
149
|
-
|
|
150
|
-
- **Session start** builds the initial inventory and SQLite FTS index.
|
|
151
|
-
- **Auto-refresh** (default) rescans roots before retrieval when any `SKILL.md` path changes. This is a directory walk only; it rebuilds the FTS index when the fingerprint changes.
|
|
152
|
-
- **Manual refresh** via `/shiori:reload` always rebuilds the inventory and FTS index immediately.
|
|
153
|
-
- Disable auto-refresh when you prefer a fixed snapshot:
|
|
154
|
-
|
|
155
|
-
```yaml
|
|
156
|
-
inventory:
|
|
157
|
-
autoRefreshOnChange: false
|
|
158
|
-
roots:
|
|
159
|
-
- custom-skills
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Cost/latency trade-offs:
|
|
163
|
-
|
|
164
|
-
- Auto-refresh adds a shallow filesystem walk on each agent turn while enabled. It avoids stale search results after local skill edits without restarting Pi.
|
|
165
|
-
- A full refresh rebuilds the SQLite FTS database and scales with total indexed skills and description length. Large vaults with many roots may prefer `autoRefreshOnChange: false` plus explicit `/shiori:reload` after bulk imports.
|
|
166
|
-
- Search stays description-first and policy-aware: only `triggerable` skills become candidates, with FTS ranking over names, descriptions, and policy triggers.
|
|
167
|
-
|
|
168
|
-
## Configure
|
|
169
|
-
|
|
170
|
-
Create `.pi/skill-shiori.yml` in the project where Pi runs.
|
|
171
|
-
|
|
172
|
-
Minimal config:
|
|
173
|
-
|
|
174
|
-
```yaml
|
|
175
|
-
zeroCatalog:
|
|
176
|
-
enabled: true
|
|
177
|
-
|
|
178
|
-
defaults:
|
|
179
|
-
activation: explicit
|
|
180
|
-
|
|
181
|
-
candidateInjection:
|
|
182
|
-
maxCandidates: 3
|
|
183
|
-
minScore: 0.62
|
|
184
|
-
|
|
185
|
-
alwaysVisible:
|
|
186
|
-
- pi-skill-shiori
|
|
187
|
-
|
|
188
|
-
skills:
|
|
189
|
-
reddit-research:
|
|
190
|
-
activation: triggerable
|
|
191
|
-
triggers:
|
|
192
|
-
include:
|
|
193
|
-
- Reddit
|
|
194
|
-
- Redditで調べて
|
|
195
|
-
- reputation on Reddit
|
|
196
|
-
exclude: []
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
Policy rules:
|
|
200
|
-
|
|
201
|
-
- `defaults.activation: explicit` is the safe default. Unlisted skills are not auto-candidates.
|
|
202
|
-
- `activation: triggerable` allows Shiori to recommend the skill for matching requests.
|
|
203
|
-
- `alwaysVisible` lists skills that should remain visible in the Skill Catalog during Zero-Catalog Mode. Use this for a tiny safety-critical allowlist instead of broad trigger rules.
|
|
204
|
-
- Missing `alwaysVisible` entries are reported by `/shiori:doctor` and warned once per session when Zero-Catalog Mode runs.
|
|
205
|
-
- `candidateInjection.maxCandidates` limits how many suggestions enter the prompt.
|
|
206
|
-
- `candidateInjection.minScore` drops weak matches.
|
|
207
|
-
|
|
208
|
-
Generate a starter policy from discovered skills:
|
|
209
|
-
|
|
210
|
-
```text
|
|
211
|
-
/shiori:bootstrap
|
|
212
|
-
```
|
|
213
|
-
|
|
214
|
-
This writes a generated review file next to `.pi/skill-shiori.yml`. Review it before using it as your real policy.
|
|
215
|
-
|
|
216
|
-
## Commands
|
|
88
|
+
## Usage summary
|
|
217
89
|
|
|
218
90
|
| Command | Purpose |
|
|
219
91
|
|---|---|
|
|
220
92
|
| `/shiori:doctor` | Show policy path, indexed roots, inventory count, retrieval backend, suppression status, and code marker. |
|
|
221
93
|
| `/shiori:bootstrap` | Generate a review draft policy from discovered skill descriptions. |
|
|
222
|
-
| `/shiori:reload` |
|
|
223
|
-
| `/shiori:recommend` |
|
|
224
|
-
| `/shiori:stats` | Show operational counters and
|
|
225
|
-
|
|
226
|
-
## Tool
|
|
94
|
+
| `/shiori:reload` | Rebuild Shiori skill inventory; optionally ask Pi to reload runtime resources. |
|
|
95
|
+
| `/shiori:recommend` | Interactive recommendation flow with optional pre-load. |
|
|
96
|
+
| `/shiori:stats` | Show operational counters and recommendation quality summary. |
|
|
227
97
|
|
|
228
98
|
Shiori registers one tool:
|
|
229
99
|
|
|
@@ -231,94 +101,22 @@ Shiori registers one tool:
|
|
|
231
101
|
shiori_load_skill({ skill: "reddit-research" })
|
|
232
102
|
```
|
|
233
103
|
|
|
234
|
-
The model receives the full selected `SKILL.md` content. The Pi UI shows a compact result like
|
|
104
|
+
The model receives the full selected `SKILL.md` content. The Pi UI shows a compact result like `✓ Loaded reddit-research (6.3KB)`.
|
|
235
105
|
|
|
236
|
-
|
|
237
|
-
✓ Loaded reddit-research (6.3KB)
|
|
238
|
-
```
|
|
106
|
+
Recommended skills show compact reason badges (`[trigger]`, `[description]`, `[low match]`). See [`Docs/recommendation-surface.md`](Docs/recommendation-surface.md) for badge vocabulary and metrics interplay.
|
|
239
107
|
|
|
240
|
-
|
|
108
|
+
For inventory roots, policy YAML, suppression statuses, and feedback metrics, see [`Docs/usage.md`](Docs/usage.md).
|
|
241
109
|
|
|
242
|
-
|
|
110
|
+
## Package contents
|
|
243
111
|
|
|
244
|
-
|
|
|
112
|
+
| Path | Purpose |
|
|
245
113
|
|---|---|
|
|
246
|
-
| `
|
|
247
|
-
| `
|
|
248
|
-
| `
|
|
249
|
-
| `
|
|
250
|
-
|
|
251
|
-
`
|
|
252
|
-
|
|
253
|
-
## Retrieval backend
|
|
254
|
-
|
|
255
|
-
Shiori prefers `sqlite-fts` using Node’s built-in `node:sqlite` and FTS5. If that is unavailable, it falls back to `token-match`.
|
|
256
|
-
|
|
257
|
-
Check backend:
|
|
258
|
-
|
|
259
|
-
```text
|
|
260
|
-
/shiori:doctor
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
Example:
|
|
264
|
-
|
|
265
|
-
```text
|
|
266
|
-
retrievalBackend: sqlite-fts
|
|
267
|
-
code: prompt-boundary-v3
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
## Recommendation reason badges
|
|
271
|
-
|
|
272
|
-
Recommended skills show compact reason badges so you can see why Shiori surfaced them:
|
|
273
|
-
|
|
274
|
-
- `[trigger]` — a policy trigger phrase matched
|
|
275
|
-
- `[description]` — skill name/description tokens matched strongly
|
|
276
|
-
- `[low match]` — passed `minScore` but near the threshold
|
|
277
|
-
|
|
278
|
-
Badges appear in auto-inject candidates, `/shiori:recommend` review mode, pre-load summaries, and the `shiori_recommend` tool line. Unclassified matches omit the badge instead of showing a long explanation.
|
|
279
|
-
|
|
280
|
-
Example with multiple surfaced skills:
|
|
281
|
-
|
|
282
|
-
```text
|
|
283
|
-
Matched 2 skill(s): playwright-cli [trigger], gstack-browse [description]
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
See [`Docs/recommendation-surface.md`](Docs/recommendation-surface.md) for how badges relate to Always Visible Skill policy and recommendation feedback metrics.
|
|
287
|
-
|
|
288
|
-
## Recommendation feedback metrics
|
|
289
|
-
|
|
290
|
-
`/shiori:stats` includes session-local recommendation feedback so operators can tune trigger rules from real outcomes instead of guesswork.
|
|
291
|
-
|
|
292
|
-
Recorded (bounded, in-memory for the current Pi session):
|
|
293
|
-
|
|
294
|
-
- recommendation offers and candidate slot counts per source (`auto-inject`, `command`, `tool`)
|
|
295
|
-
- load follow-through when recommended skills are pre-loaded or later loaded via `shiori_load_skill`
|
|
296
|
-
- abandoned recommendation flows (candidates shown but not loaded, e.g. review-only mode)
|
|
297
|
-
- zero-candidate queries (obvious misses)
|
|
298
|
-
- per-skill offered/loaded tallies (up to 50 skill names, oldest entries dropped first)
|
|
299
|
-
|
|
300
|
-
Not recorded:
|
|
301
|
-
|
|
302
|
-
- user prompts, task descriptions, or transcript bodies
|
|
303
|
-
- skill `SKILL.md` contents
|
|
304
|
-
- filesystem paths beyond skill names already visible in policy/inventory
|
|
305
|
-
|
|
306
|
-
Retention boundary:
|
|
307
|
-
|
|
308
|
-
- counters reset when the Pi session ends
|
|
309
|
-
- no disk persistence or cross-session analytics in this slice
|
|
310
|
-
- inspect the compact summary at the top of `/shiori:stats`, with full JSON below
|
|
311
|
-
|
|
312
|
-
Example summary line:
|
|
313
|
-
|
|
314
|
-
```text
|
|
315
|
-
Recommendation feedback (session-local, no prompts stored)
|
|
316
|
-
offers: 4 | candidate slots: 7 | loaded: 3
|
|
317
|
-
abandoned: 1 | zero-candidate queries: 2 | follow-through: 42.9%
|
|
318
|
-
auto-inject: offers=2, loaded=1, zeroHits=1
|
|
319
|
-
command: offers=1, loaded=2, zeroHits=1
|
|
320
|
-
top skills: auth-helper(1/2), deploy-kit(1/1)
|
|
321
|
-
```
|
|
114
|
+
| `src/` | Pi extension entrypoint and Shiori runtime |
|
|
115
|
+
| `Docs/usage.md` | Configuration, inventory, suppression, and metrics details |
|
|
116
|
+
| `Docs/recommendation-surface.md` | Recommendation badges and surface behavior |
|
|
117
|
+
| `ROADMAP.md` | Maintenance direction and phased plan |
|
|
118
|
+
| `CHANGELOG.md` | Version history |
|
|
119
|
+
| `SECURITY.md` | Vulnerability reporting |
|
|
322
120
|
|
|
323
121
|
## Development
|
|
324
122
|
|
|
@@ -327,6 +125,7 @@ git clone https://github.com/eiei114/pi-skill-shiori.git
|
|
|
327
125
|
cd pi-skill-shiori
|
|
328
126
|
npm install
|
|
329
127
|
npm run typecheck
|
|
128
|
+
npm test
|
|
330
129
|
```
|
|
331
130
|
|
|
332
131
|
Run in a Pi project without installing globally:
|
|
@@ -335,59 +134,40 @@ Run in a Pi project without installing globally:
|
|
|
335
134
|
pi -e /absolute/path/to/pi-skill-shiori
|
|
336
135
|
```
|
|
337
136
|
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
```bash
|
|
341
|
-
npm run typecheck
|
|
342
|
-
npm test
|
|
343
|
-
```
|
|
137
|
+
## Release
|
|
344
138
|
|
|
139
|
+
Releases are automated via Trusted Publishing:
|
|
345
140
|
|
|
346
|
-
|
|
141
|
+
1. Bump `version` in `package.json` and update `CHANGELOG.md`.
|
|
142
|
+
2. Merge to `main`.
|
|
143
|
+
3. **Auto Release** tags `v<version>` and creates a GitHub release.
|
|
144
|
+
4. The tag triggers **Publish**, which publishes to npm with provenance.
|
|
347
145
|
|
|
348
|
-
|
|
146
|
+
Maintainer checks before merge:
|
|
349
147
|
|
|
350
148
|
```bash
|
|
351
149
|
npm run typecheck
|
|
352
150
|
npm test
|
|
353
151
|
npm run release:npm:dry
|
|
354
|
-
npm whoami
|
|
355
|
-
npm run release:npm
|
|
356
152
|
```
|
|
357
153
|
|
|
358
154
|
For version history, see [`CHANGELOG.md`](CHANGELOG.md).
|
|
359
155
|
|
|
360
|
-
For a first-time publish, login first:
|
|
361
|
-
|
|
362
|
-
```bash
|
|
363
|
-
npm login
|
|
364
|
-
```
|
|
365
|
-
|
|
366
|
-
After publishing, verify the Pi install path:
|
|
367
|
-
|
|
368
|
-
```bash
|
|
369
|
-
pi install npm:pi-skill-shiori@0.5.0
|
|
370
|
-
pi install npm:pi-skill-shiori
|
|
371
|
-
pi list
|
|
372
|
-
/shiori:doctor
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
For future versions:
|
|
376
|
-
|
|
377
|
-
```bash
|
|
378
|
-
npm version patch
|
|
379
|
-
git push --follow-tags
|
|
380
|
-
npm run release:npm
|
|
381
|
-
```
|
|
382
|
-
|
|
383
156
|
## Security
|
|
384
157
|
|
|
385
158
|
Pi packages execute local code with the same permissions as Pi. Review third-party packages before installing them.
|
|
386
159
|
|
|
387
|
-
Shiori
|
|
160
|
+
Shiori does not sandbox skills. It only changes how skill candidates are discovered and loaded. A loaded skill can still instruct the model to run tools, edit files, or execute commands according to your Pi/tool permissions.
|
|
388
161
|
|
|
389
162
|
For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
|
|
390
163
|
|
|
164
|
+
## Links
|
|
165
|
+
|
|
166
|
+
- **Repository**: <https://github.com/eiei114/pi-skill-shiori>
|
|
167
|
+
- **npm**: <https://www.npmjs.com/package/pi-skill-shiori>
|
|
168
|
+
- **Issues**: <https://github.com/eiei114/pi-skill-shiori/issues>
|
|
169
|
+
- **Pi packages**: <https://pi.dev/packages>
|
|
170
|
+
|
|
391
171
|
## License
|
|
392
172
|
|
|
393
173
|
MIT
|
package/ROADMAP.md
CHANGED
|
@@ -57,7 +57,7 @@ semver classification. Patches default to `patch`; `none` means no package publi
|
|
|
57
57
|
|
|
58
58
|
| # | Slice | Bump | Status |
|
|
59
59
|
|---|---|---|---|
|
|
60
|
-
| 1 | Add README status badges (CI, Publish, npm version, npm downloads, License, Pi package, Trusted Publishing) | patch |
|
|
60
|
+
| 1 | Add README status badges (CI, Publish, npm version, npm downloads, License, Pi package, Trusted Publishing) | patch | done |
|
|
61
61
|
| 2 | Add `version:check` CI gate (block publishable-path changes without a semver increase) | none | planned |
|
|
62
62
|
| 3 | Pin GitHub Actions to commit SHAs in `ci.yml`, `auto-release.yml`, `publish.yml` | none | planned |
|
|
63
63
|
|
package/package.json
CHANGED
|
@@ -18,9 +18,7 @@ export function retrieveCandidatesExpanded(
|
|
|
18
18
|
for (const variant of buildRetrievalQueries(query)) {
|
|
19
19
|
for (const candidate of retrieveCandidates(variant, skills, policy, index)) {
|
|
20
20
|
const previous = byName.get(candidate.skill.name);
|
|
21
|
-
|
|
22
|
-
byName.set(candidate.skill.name, candidate);
|
|
23
|
-
}
|
|
21
|
+
byName.set(candidate.skill.name, preferExpandedCandidate(previous, candidate));
|
|
24
22
|
}
|
|
25
23
|
}
|
|
26
24
|
|
|
@@ -28,3 +26,14 @@ export function retrieveCandidatesExpanded(
|
|
|
28
26
|
.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
|
|
29
27
|
.slice(0, max);
|
|
30
28
|
}
|
|
29
|
+
|
|
30
|
+
/** Keep trigger badges when expanded query variants also score the description higher. */
|
|
31
|
+
function preferExpandedCandidate(
|
|
32
|
+
previous: SkillCandidate | undefined,
|
|
33
|
+
candidate: SkillCandidate,
|
|
34
|
+
): SkillCandidate {
|
|
35
|
+
if (!previous) return candidate;
|
|
36
|
+
if (previous.reason === "trigger") return previous;
|
|
37
|
+
if (candidate.reason === "trigger") return candidate;
|
|
38
|
+
return candidate.score > previous.score ? candidate : previous;
|
|
39
|
+
}
|