docs(skill): refresh ornn-agent-manual-cli to v1.4 — trigger description + skillset lifecycle + api-reference drift - #1183
Merged
Conversation
…1180) Claude Code auto-invokes a skill by matching its frontmatter `description` against user intent — the SKILL.md body is not consulted for routing. The old description was a static capability summary ("search / pull / execute / build / upload / share") with no trigger phrases and no mention of skillsets, plugin export, ownership transfer, GitHub sync, audits, or quota/model selection, so whole request categories never routed here. Rewrite it as an explicit "load and follow this WHENEVER the user asks to…" trigger list that names the concrete phrases an agent will hear, including every skillset operation and Claude Code plugin export. Kept to 1400 chars to stay under Claude Code's ~1536-char description budget so no trigger is truncated, with the newer skillset/plugin triggers included rather than buried past the cap. Also expand the in-doc "always load" bullet for §2.16 to surface plugin-export + ownership-transfer. Part of #1180. Related to #1085.
The manual documented `PUT /skillsets/:id/permissions` in three places — the §1.5 permission catalogue, api-reference §5a.6, and the §5a SDK line (`setSkillsetPermissions` / `set_skillset_permissions`). No such endpoint exists: skillset visibility is DERIVED from member skills, not owner-set, and the route was deliberately omitted (#1136 — routes.ts carries an explicit "there is deliberately NO PUT /skillsets/:id/permissions" note). Documenting it sends an agent to a 404. Excise all three references. The §1.5 row now points at the real `PUT /skillsets/:id/plugin-export` + `POST /skillsets/:id/transfer-ownership` (documented in the follow-up commit). The dead SDK methods are dropped from the manual's SDK line here; the SDK itself still ships `setSkillsetPermissions` against the removed route — that is separate SDK drift tracked in #1013. Part of #1180. Closes #399.
…ract (#1180) Bring the skillset section in line with the code: - Preamble: correct "visibility-scoped / visibility mirrors skills" — a skillset's visibility is DERIVED from members (#1136), not owner-set. Add two model notes: derived visibility (memberVisibilityState semantics, unreadableMembers, no-permissions-endpoint / expose-members widen-reach) and auto-revision (system-managed <major>.<minor>, reactive re-cut). - §5a.1 create / §5a.5 publish: drop the phantom `version` request field (revisions are system-assigned/auto-bumped), tighten member constraints (2..100, ≤115 chars, no `skillset:` nesting). - §5a.2 get: replace the stale response with the real SkillsetDetail — memberVisibilityState, unreadableMembers, publicMemberCount, exportAsPlugin, pluginConfig — and flag isPrivate/sharedWith*/grants as inert legacy. - §5a.4 closure: document the ClosureNode item shape { ref, name, version, depth, guid?, skillHash? }. - Add §5a.6 plugin-export (#1157, ≥2-public-members precondition) and §5a.7 transfer-ownership (#1123); renumber delete/search. - Add §5a.10 skillset error-code table; add transferSkillsetOwnership to the SDK line; correct the search params (q, scope enum, result shape). Part of #1180. Closes #1085.
The skillset workflow was physically misplaced (after §3 Conventions and
§4 References), deferred its contract to the WRONG file (the sibling
`chrono-ai-service-manual`'s `ornn-api-reference.md` instead of this
bundle's local `references/api-reference.md`, which already ships §5a),
repeated the phantom "permissions … mirror the skill endpoints" claim, and
offered no runnable commands.
Move it to its numeric home right after §2.15, point it at the local §5a,
and turn it into a real operational recipe: runnable `nyxid proxy request`
snippets for search/closure, create, publish, plugin-export, transfer, and
delete; a "no version field / revisions auto-bump" warning; and a
derived-visibility troubleshooter ("why can't my teammate see the skillset
I shared" → expose the member skills, there is no permissions endpoint).
Also fix the stale "thirteen use cases" intro (§2 now spans 16
subsections).
Part of #1180. Closes #1085.
Stamp the skill's registry version 1.3 → 1.4 and lastUpdated, reflecting the trigger-oriented description + skillset-lifecycle refresh in this PR. Empty changeset: the change is skill documentation only — the skill is registry-sourced, not bundled into the ornn-api / ornn-web images, so no package version bump. Publishing the refreshed content to the live registry is a separate operational step (manual §2.3). Part of #1180.
Two skill-lifecycle endpoint families existed in ornn-api but were absent from the manual: - §3.16 POST /skills/:id/transfer-ownership (#1123) — ADMIN-tier hand-off, prior owner kept as READ, target must be a known Ornn user. - §3.17 GET/PUT/DELETE /skills/:id/dist-tags[/:tag] (#463) — npm-style named version pointers, `latest` auto-managed + immutable, tag grammar /^[a-z][a-z0-9-]{0,49}$/, resolvable via @<tag> refs. Both grounded verbatim against crud/routes.ts + service.ts (auth tiers, scopes, bodies, response shapes, error codes). Part of #1180. Closes #399.
…1180) - §8a POST /assistant/chat (#970) — repo-aware, non-agentic Q&A SSE with the real four-event contract (chat_start / chat_text_delta / chat_finish / chat_error), 30/min rate limit, and `assistant`-surface quota charging. Verified event names + limit against assistant/chatService.ts + routes.ts. - §6.3 GET /skill-manifest-schema.json (#464) — public draft-2020-12 schema for SKILL.md frontmatter, flagged as the one endpoint that returns a raw (un-enveloped) body for editor `$schema` consumption. TOC gains an 8a entry. Part of #1180. Closes #399.
- §2.4 GET /github/repo — public mirror coordinates {owner,repo,branch,
enabled} (credentials never exposed); the install-snippet source.
- §13.8 POST /github/repo — admin direct mirror-config patch (kill-switch,
coords, GitHub App creds; secrets mid-masked; confirmAbandonOldRepo guard).
- §11.13 GET /me/launch-promo — caller's promo claim status (#724).
- §13.11 admin launch-promo award + recent-claims observability (#724).
Part of #1180. Closes #399.
…1180) - §14.3: the per-model PATCH body was missing the `assistant` surface flags (enabledForAssistant / defaultForAssistant) added by #970, and the section intro said "two SSE surfaces" — now three (playground/skillGen/assistant). Added the ≥1-flag + atomic-default invariants and MODEL_NOT_FOUND/ MODEL_REMOVED errors. - Quota scope: the manual documented `ornn:quota:admin` for quota / redemption-codes / dashboard-stats, but that string exists nowhere in the API — QUOTA_ADMIN_PERMISSION is an alias whose value is `ornn:admin:skill` (quota/types.ts:36). Corrected §1.5 (both files), §13.6, and §13.7 to the real scope and folded the redundant row into `ornn:admin:skill`. Part of #1180. Closes #399.
The refresh grew beyond skillsets to a full api-reference drift pass (skill transfer-ownership, dist-tags, assistant SSE, manifest schema, github/repo mirror coords, launch-promo, per-model assistant surface, quota-scope fix). Reflect that in the changeset summary. Still docs-only. Part of #1180.
This was referenced Jul 1, 2026
[Docs] Skill manuals reference removed endpoints — refresh
api-reference.md against current API
#399
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refreshes Ornn's own core agent skill
ornn-agent-manual-clito v1.4: makes it reliably auto-invoke in Claude Code, and brings its skillset coverage + the wholereferences/api-reference.mdback in line with the currentornn-apicontract. Every change was grounded against the code via a code-verified audit (phantom/missing/stale endpoints confirmed atfile:line, not eyeballed).Why
description, not its body. The old description was a static capability blurb with no trigger phrases and no mention of skillsets/plugin-export — so whole request classes never reached this skill.PUT /skillsets/:id/permissions, deleted in [Feature] Member-derived skillset visibility (no manual control) + lost-access warnings & owner notifications #1136), omitted every recent endpoint (skillset plugin-export/transfer, skill transfer/dist-tags, assistant SSE, manifest schema, mirror coords, launch-promo), showed a phantomversionrequest field, and misnamed a permission scope (ornn:quota:admin, which exists nowhere in the API).What changed
Discoverability
description(1400 chars, under Claude Code's budget) covering skills and skillsets, plugin export, ownership transfer, GitHub sync, audits, quota/model selection.Skillsets (SKILL.md §2.16 + api-reference §5a) — the "skillset info isn't in yet" gap
PUT /skillsets/:id/permissionseverywhere (section, §1.5 table row, SDK line).memberVisibilityState,unreadableMembers, no-permissions / expose-members widen-reach) and auto-revision (system-managed<major>.<minor>, no callerversion).SkillsetDetailresponse (addedmemberVisibilityState/unreadableMembers/publicMemberCount/exportAsPlugin/pluginConfig; flagged inert legacy ACL fields) and theClosureNodeshape.plugin-export([Feature] Move skillset plugin export to a detail-page card + confirm modal #1157) +transfer-ownership([Feature] Skill permission levels (read / read-write) + ownership transfer #1123) subsections, a skillset error-code table, and runnablenyxid proxy requestrecipes; relocated §2.16 to its numeric home; fixed the wrong-reference-file bug + the stale "thirteen use cases".Broader api-reference drift
transfer-ownership(§3.16, [Feature] Skill permission levels (read / read-write) + ownership transfer #1123) + dist-tags (§3.17, [Feature] Dist-tags (latest / stable / next) for skill version resolution #463).GET /github/repomirror coords (§2.4) + adminPOST /github/repo(§13.8); launch-promo (§11.13 + §13.11, [Bug] [Launch Promo] GitHub Star reward delivery is promised, but automatic eligibility and redemption-code issuance are not implemented in Ornn #724).assistantsurface flags in §14.3 ([Feature] Ornn Assistant — repo-aware Q&A chatbot (API + web widget) #970); corrected the phantomornn:quota:admin→ realornn:admin:skill(QUOTA_ADMIN_PERMISSIONalias) in §1.5/§13.6/§13.7.Commits
10 small, self-contained commits (description → phantom removal → §5a refresh → §2.16 rewrite → v1.4 + changeset → transfer/dist-tags → assistant/manifest → github-repo/launch-promo → assistant-surface/quota-scope → changeset scope).
Verification
assistant-kb-freshness: rebuilt digest — no diff (the KB manifest indexes the http variant, not this cli one).skillsets/:id/permissionsorPermission: ornn:quota:adminleft.changeset statusvalid (empty / docs-only — the skill is registry-sourced, not bundled into either package image).Notes
ornn-api/ornn-webruntime change. Publishing the refreshed content to the live registry is a separate operational step (manual §2.3).setSkillsetPermissionstargeting the removed route — that's SDK drift, tracked in [Bug] SDK types, update payload, and search filters have drifted from the real API contract (TS + Python) #1013 (out of scope here).ornn-agent-manual-cliscope of [Docs] Skill manuals reference removed endpoints — refreshapi-reference.mdagainst current API #399 and [Feature] Document full skillset lifecycle in ornn-agent-manual-cli (and chrono-ai-service-manual) #1085; the siblingchrono-ai-service-manualrefresh is tracked in [Docs] Apply the skillset-lifecycle + api-reference refresh to chrono-ai-service-manual #1182.Closes #1180
🤖 Generated with Claude Code