@hasna/skills 0.10.88 → 0.10.89

package/README.md

@@ -1019,10 +1019,43 @@ offered as `skills load` commands instead of being injected or picked by name
 order. Weaker pointers are offered the same way, at most three and never
 injected: a multi-word keyword whose words all appear apart, one of them
 discriminating ("designs review" in "the designs app for review"), or a common
-one-word keyword; a tie that does not fit is left out.
+one-word keyword; a tie that does not fit is left out. Managed prompt hooks are
+stricter than a direct `skills context` call: they inject an unnamed prompt
+match only for a phrase of two or more words, and offer anything weaker as a
+`skills load` command, so a `keywords: ["pdf"]` selection needs `$pdf`, "the pdf
+skill", a two-word keyword or `triggers.always` to arrive as a body.
+`SKILLS_HOOK_PROMPT_MIN_PHRASE_WORDS` can raise that length, never lower it.
+Sumi's plugin and Cursor's prompt hook discard a prompt call's output, so a
+pointer could not reach their models, and they keep the plain selection. Each
+`skills load` command a session is offered names that session and carries
+`--cache-first`, so it loads the pinned version from the verified cache the hook
+used, which works in a sandbox with no network. Once the cache can't serve it it
+loads from the Skills service. That happens when the pin was last verified over
+24 hours ago, which is common for a subagent, since it inherits its parent's time
+and no hook renews its own pin. With no network as well, the load refuses and says
+so, and `skills sync` doesn't renew a session's pin. Like a body the hook delivers
+from the cache, a cached load doesn't ask the service whether the selection is
+still current.
+
+A load is recorded on the session the command names, whoever runs it, so running
+another session's command marks that session as having loaded the skill, and its
+later prompts offer it no pointer. Where the session store can't be written or is
+full, as in a Codex sandbox, a load still returns its content and says it wasn't
+recorded, unless the bundle isn't cached and the cache can't be written either, in
+which case it refuses. Compaction won't restore an unrecorded skill and the session
+won't be told if it's retired. An agent or subagent with no way to run a command can't use a
+pointer.
+
 A session retains its loaded selections; compaction restores the two most
-recently loaded instructions, and a subagent receives its parent's most recent
-one, each followed by `skills load` commands for the next most recent. A
+recently loaded instructions, followed by `skills load` commands for the next
+most recent. A subagent started by a managed hook is offered its parent's
+loaded skills as `skills load` commands, and gets a body at its start only for a
+skill that `triggers.always` or a path selects. Claude Code's and Codex's
+subagent start carries no prompt, so naming a skill in a subagent's brief doesn't
+deliver its body there. OpenCode's adapter does pass the subagent's first prompt,
+so there it also gets a body for a skill it names or matches by a phrase. A
+direct `skills context` call, and Sumi's and Cursor's hooks, give it its parent's
+most recent one as a body. A
 read-only prompt does not rewrite the session receipt or take its write lock
 (a damaged lock still refuses), and receipt writers wait up to two seconds for
 another live writer's lock before refusing; a lock another writer is