docs: tighten prose audit after master retarget

packages/skill/skill/README.md

@@ -21,11 +21,11 @@ This package owns the `ctx.skills` interface. It does not know whether skills co
 
 ## Provider Contract
 
-A provider registers synchronously from its `apply()` and returns `readonly SkillCandidate[]` from `list(options)` when discovery is requested. The provider, lookup options, candidates, and loaded definitions are readonly same-process contracts: the registry borrows them rather than cloning, freezing, or rebinding callbacks. Remote setup, authentication, and discovery belong in the awaited `list()` call rather than plugin registration. Providers should stop promptly when `options.signal` aborts; the registry also stops awaiting uncooperative discovery and loading work so agent cancellation cannot hang prefix composition or skill loading.
+A provider registers synchronously and performs remote setup, authentication, and discovery in its awaited `list(options)` call. Provider objects, lookup options, candidates, and definitions are borrowed readonly rather than cloned or rebound. Providers should honor `options.signal`; the registry also stops awaiting uncooperative discovery or loading after cancellation.
 
-The registry validates parsed provider candidates before caching them and validates loaded definitions before returning them. The winning provider receives the exact candidate and opaque `locator` identity it returned from `list()`; a local provider can therefore use a file-path handle while a remote provider can use a URL, id, or version token. Callers and providers must honor the readonly contract after handing values to the registry.
+The registry validates candidates before caching and definitions before returning them. The winning provider receives the same candidate and opaque `locator` it returned from `list()`, allowing backend-specific file, URL, id, or version handles. Callers and providers must preserve the readonly contract.
 
-Parsed candidate and loaded-definition fields are validated at the provider boundary: names/descriptions/content use their declared string types, ranks are finite numbers, and `disableModelInvocation` is boolean when present. Candidate contract violations fail fast because the provider or its parser is malformed; a provider `list()` rejection is treated as a transient source failure, logged, skipped for that request, and not cached. Only completed catalogs are cached, and a provider/runtime revision change during discovery discards the stale result and retries. Duplicate skill names are resolved first-wins by `rank`, provider registration order, then the provider's own local order. The final summary list is sorted by skill `name` for deterministic consumers.
+Contract violations fail fast. A rejected `list()` is treated as a transient source failure: it is logged, skipped, and not cached. Only completed catalogs are cached; a provider or runtime revision change discards an in-flight result and retries. Duplicate names resolve by rank, provider registration order, then provider-local order. Summaries are sorted by skill name.
 
 ## Runtime Skills
 

packages/skill/skill/src/index.ts

@@ -175,14 +175,9 @@ export class SkillService extends Service {
   }
 
   /**
-   * Register a skill provider synchronously during the provider plugin's
-   * `apply()`. Throws if another provider already owns the same provider name,
-   * including the reserved runtime provider name. Providers that need remote
-   * initialization do that work inside `list()` after registration. Providers
-   * are readonly same-process registrations: the registry borrows the provider
-   * object and invokes its methods directly. Effect-scoped and HMR-safe:
-   * disposing the caller's fiber unregisters the provider and invalidates
-   * cached catalogs.
+   * Register a borrowed same-process provider. Duplicate and reserved names
+   * throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+   * the provider and invalidates catalog caches.
    * @param provider - the provider to register by `provider.name`.
    * @returns the exact Cordis effect disposer that unregisters this provider;
    *   composite effects may yield it directly to preserve teardown ordering.
@@ -215,16 +210,11 @@ export class SkillService extends Service {
   }
 
   /**
-   * Register a runtime skill contribution. Runtime registrations are treated as
-   * embedded provider entries with project-over-user priority. Same-name runtime
-   * registrations are first-wins: a duplicate logs a warning and gets a no-op
-   * disposer so it cannot remove the active contribution. Runtime definitions
-   * are readonly same-process registrations; the registry borrows their nested
-   * resource metadata.
+   * Register a borrowed readonly runtime skill. Project entries outrank runtime
+   * entries, which outrank user entries. A duplicate is ignored with a no-op
+   * disposer so it cannot remove the first registration.
    * @param skill - the complete skill definition to expose for discovery.
-   * @returns the exact Cordis effect disposer that removes this runtime
-   *   contribution and invalidates caches; composite effects may yield it
-   *   directly to preserve teardown ordering.
+   * @returns the exact Cordis disposer, which also invalidates caches.
    */
   register(skill: SkillRegistration): () => void {
     validateRuntimeSkill(skill)
@@ -266,12 +256,8 @@ export class SkillService extends Service {
   }
 
   /**
-   * Load one full skill definition by name. The provider receives the winning
-   * candidate it returned during discovery, including its opaque locator, and
-   * the registry returns the provider's definition after validating it.
-   * Cancellation is rechecked after catalog
-   * selection (including a cache hit), and provider loading is raced against the
-   * same signal so an uncooperative provider cannot hang the caller.
+   * Load and validate the winning provider candidate. Cancellation is checked
+   * after selection and raced against provider loading.
    * @param name - kebab-case skill name.
    * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
    * @returns the full skill, including body content, or `undefined`.