maka/docs/skill-catalog-policy.md

<!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
-->

# Skill catalog policy

Maka keeps skill bodies out of the always-on system prompt. The prompt contains
only a bounded catalog; the read-only `Skill` tool loads full instructions when
a task matches a skill.

Discovery produces both a complete inventory and a winner catalog. Every valid
copy has a scope-aware `ref` (for example `project:maka:writer` or
`user:agents:writer`). Duplicate ids remain in the inventory for inspection,
but only the highest-precedence copy is eligible for the runtime catalog.

The catalog is selected deterministically in this order:

1. Discover skill directories in source precedence order. Project-level paths
   precede workspace compatibility paths, which precede user-level paths.
   Duplicate ids use first-found wins. Skills within one directory are ordered
   by display name.
2. Exclude disabled skills.
3. When the host supplies capabilities, exclude skills whose explicit
   `required-tools` or `required-capabilities` are unavailable. `allowed-tools`
   remains informational and never grants permission.
4. Put user-pinned skills first, then preserve source precedence and stable
   display-name/ref ordering.
5. Add catalog entries in the resulting order until the selected model's
   catalog budget is reached. The budget is 2% of its context window, clamped
   to 4,000–8,000 estimated tokens and converted at four characters per token.
   If the context window is unavailable, use the backward-compatible
   `MAX_SKILLS_PROMPT_CHARS = 18000` character budget.

The lower bound keeps useful catalogs available on small-context models. The
upper bound prevents large-context models from turning the catalog into an
unbounded always-on cost. Because changing models can change the selected
catalog, the model context window is an explicit prompt input rather than an
implicit provider lookup inside the skill scanner.

When the budget omits entries, the prompt contains only a constant-size count,
not an unbounded list of ids. Omission affects only catalog advertisement: an
enabled, host-compatible omitted skill remains discoverable through the bounded
metadata-only `SkillSearch` tool and loadable by exact ref, id, or name through
the `Skill` tool. Skill instructions remain subject to their separate lazy-load
body limit.

`selectSkillsForContext` returns a `SkillSelectionReport` alongside the selected
catalog. It records one decision for every inventory item (`advertised`,
`budget`, `disabled`, `invalid`, `host_incompatible`, or `shadowed`) and the
advertised rank. Desktop caches the last prompt-build report per project for
its Context Inspector; before a prompt has been built, it displays a
deterministic preview.

Runtime preferences use `.maka/skills-state.json` schema v2:

```json
{
  "schemaVersion": 2,
  "skills": {
    "workspace:legacy:writer": {
      "enabled": true,
      "pinned": true,
      "updatedAt": "2026-07-22T00:00:00.000Z"
    }
  }
}
```

The reader remains compatible with schema v1 id keys. Desktop migrates an id
automatically only when it resolves to one inventory entry. If the id exists in
multiple scopes, schema v2 preserves the legacy default under
`migration.needsReview` until the user makes explicit ref-level choices; it
never guesses which copy the old preference meant. The Skills Context Inspector
shows every affected copy as `Needs review`; toggling or pinning acts on its
exact ref, and the marker clears only after every ambiguous copy has an explicit
preference.

Bundled provenance is not an execution authority over local workspace content.
Removing an entry from `BUNDLED_SKILL_CATALOG` stops Maka from distributing or
installing that source and makes an older bundled lock fail validation with
`metadata_error`. An upgrade does not delete, rewrite, or silently disable the
already-installed `skills/<id>` directory. If that local copy is otherwise
valid and enabled, Runtime continues to treat it as user-provided content and it
remains invocable under the ordinary permission and host-capability rules. The
user can disable or delete the local copy explicitly.

Configured discovery roots are also part of the diagnostic contract. A missing
optional root is normal and produces no warning. A symlink/non-directory root,
containment escape, or unreadable root produces a bounded
`SkillDiscoveryDiagnostic` (`blocked_path` or `read_failed`) and appears in the
Desktop inventory. It must not be collapsed into an indistinguishable empty
catalog.

## Explicit invocation contract

New Desktop selections store and submit the stable `ref` returned by
`listInvocableSkills`. The legacy `skillIds` wire-field name remains accepted
and may contain either an exact ref or a legacy id; `/skill:<id>` remains
supported for typed CLI/Desktop input. Send-time resolution is authoritative
and deterministic: exact ref, then id, then name.

Desktop and CLI both use `prepareSkillInvocationMessage`:

- successful requests inject the bounded Skill body and remove invocation
  markers before provider handoff;
- partial failures keep the successful skills and report each failure;
- if every explicit request fails, no provider turn is created;
- if the combined structured and text inputs exceed 50 distinct requests,
  preparation fails closed with one bounded `too_many_requests` diagnostic;
  Runtime resolves no partial request set and creates no provider turn;
- within the limit, each distinct request returns one bounded
  `SkillInvocationReceipt` with
  `invocation`, success/failure, exact ref/scope/source for successful loads,
  truncation, and a failure reason. Receipts contain no user prompt, search
  query, or Skill instructions.

Model `Skill` tool loads use the same receipt projection for run-trace data with
`invocation: model_tool`; these projections are durable AgentRun trace events.
Explicit client receipts use `invocation: explicit` and are intentionally
client-local, ephemeral preparation diagnostics: they are returned to the
submitting client, but are not restored with the session or correlated with a
durable run. Failed trace projections retain only request length, not the
requested text. This makes the outcome shapes comparable without creating a
new content-collection channel or implying that pre-turn diagnostics are a
durable audit trail.

Prompt construction, `SkillSearch`, and `Skill` emit diagnostic run-trace
events. Search telemetry stores counts and query length rather than raw query
text. The shadow evaluator retains at most the top 20 refs for the current turn;
when a searched skill is subsequently loaded, the load event records its rank
and Top-1/Top-5/Top-20 hit flags. This measures ranking quality without
collecting skill instructions or user query content.

## Governance closeout boundary

This policy closes the local Skill governance work when Runtime, Desktop, and
CLI contract tests cover duplicate/shadowed ids, invalid metadata, disabled and
host-incompatible skills, prompt-budget omission, stable-ref explicit
invocation, all-failed no-turn behavior, migration review, and discovery-source
diagnostics.

Remote marketplaces and automatic updates, self-modifying/evolving Skills, a
full-screen TUI manager, embedding-based ranking, and analytics dashboards are
separate product initiatives. They are not prerequisites for a safe,
deterministic local Skill lifecycle.