{
  "schemaVersion": 1,
  "updatedAt": "2026-10-15",
  "contracts": [
    {
      "harness": "codex",
      "variant": "initial-list-documented",
      "default": true,
      "initialFields": ["name", "description", "path"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": 0.02,
        "fallback": {
          "unit": "characters",
          "value": 8000,
          "condition": "context-window-unknown"
        }
      },
      "overflow": ["shorten-descriptions", "may-omit-skills"],
      "allNamesRetained": false,
      "warning": "user-warning",
      "configuration": [
        "skills.max_context_tokens",
        "skills.include_instructions",
        "skills.bundled.enabled",
        "[[skills.config]] enabled"
      ],
      "evidence": ["codex-skill-listing-docs"],
      "reference": "https://learn.chatgpt.com/docs/build-skills#mainContent",
      "notes": ["Budget applies to initial listing, not the full selected SKILL.md."],
      "sourceBehavior": {
        "stability": "source-observed",
        "clientVersion": "0.162.1",
        "sourceRevision": "092d3acd6bec3e3a14bdc7e7a2810ab628ab759d",
        "evidence": [
          "codex-skill-render-0.162.1-source",
          "codex-token-accounting-0.162.1-source",
          "codex-skill-policy-host-0.162.1-source",
          "codex-skill-policy-executor-0.162.1-source",
          "codex-skill-visible-catalog-0.162.1-source"
        ],
        "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/ext/skills/src/render.rs#L126-L155",
        "budgetUnit": "approximate-tokens",
        "configurationOverride": {
          "field": "skills.max_context_tokens",
          "maximum": 10000
        },
        "accounting": "ceil-utf8-bytes-divided-by-four-per-row",
        "descriptionCap": 1024,
        "initialTruncation": {
          "prefixCharacters": 1021,
          "suffix": "..."
        },
        "overflowAllocation": "round-robin-description-prefixes",
        "overflowSuffix": "",
        "notes": [
          "Known-window default is floor(2% of context tokens), at least one; unknown-window fallback is 8,000 Unicode scalar characters. The positive configured token override takes priority and is capped at 10,000.",
          "Rows charge names, descriptions, locators/paths, separators and trailing newlines. Full rendered demand additionally includes shared listing overhead; allocator metadata cost is not necessarily the whole prompt cost. Alias tables/instructions and omission notices are accounted where applicable.",
          "Minimum rows that cannot fit may be omitted. Budget trimming does not append ellipses; the prior per-description cap does.",
          "Full demand before either description trimming stage must be distinguished from fitted listing demand. Neither is tokenizer or billing usage. These observations apply to this revision, not all Codex versions.",
          "At this revision, policy.allow_implicit_invocation: false in agents/openai.yaml hides host and executor skills from the model-visible catalog. PreparedSkillCatalog filters them out before row construction, alias planning and budget allocation, so their names, descriptions and paths incur no initial listing cost. Explicit $skill invocation remains available and loads instructions into conversation context outside the listing budget.",
          "Rechecked against released 0.162.1 on October 15. The renderer and visible-catalog filter are unchanged from 0.160.1. Approximate token accounting and host/executor implicit-invocation predicates remain the same despite surrounding path/access refactors. No model request or large-catalog probe was run."
        ]
      }
    },
    {
      "harness": "claude-code",
      "variant": "initial-list-documented",
      "default": true,
      "initialFields": ["name", "description"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": 0.01,
        "fallback": null,
        "unit": "characters",
        "contextWindowConversion": "unverified"
      },
      "overflow": ["drop-descriptions-least-invoked-first"],
      "allNamesRetained": true,
      "warning": "debug-log",
      "configuration": [
        "skillListingBudgetFraction",
        "SLASH_COMMAND_TOOL_CHAR_BUDGET",
        "skillListingMaxDescChars",
        "skillOverrides"
      ],
      "maxDescriptionCharacters": 1536,
      "evidence": ["claude-skills-docs"],
      "reference": "https://code.claude.com/docs/en/skills#skill-descriptions-are-cut-short",
      "notes": [
        "Combined description and when_to_use text uses the per-entry character cap.",
        "Budget and per-entry cap can be configured.",
        "Name retention during overflow applies only to skills eligible for listing; explicitly hidden skills remain excluded.",
        "In regular Claude Code sessions, SKILL.md frontmatter disable-model-invocation: true excludes the description from initial context, avoiding its description-listing budget cost. Manual invocation still loads the full skill into conversation context; the listing budget does not cap that content. See https://code.claude.com/docs/en/skills#control-who-invokes-a-skill.",
        "No four-characters-per-token conversion is established or assumed."
      ],
      "nameRetentionScope": "budget-overflow-only",
      "visibility": {
        "field": "skillOverrides",
        "defaultState": "on",
        "states": {
          "on": {
            "listedFields": ["name", "description"],
            "slashMenu": true
          },
          "name-only": {
            "listedFields": ["name"],
            "slashMenu": true
          },
          "user-invocable-only": {
            "listedFields": [],
            "slashMenu": true
          },
          "off": {
            "listedFields": [],
            "slashMenu": false
          }
        },
        "userProjectLocalMatching": "skill-name-only",
        "pluginSkillsAffected": false,
        "aliasMatching": {
          "versionAdded": "2.1.260",
          "scopes": ["managed", "--settings"],
          "behavior": "restrict-only",
          "namePrecedence": "managed-own-name-over-alias"
        },
        "crossFileMapMerging": "unverified",
        "reference": "https://code.claude.com/docs/en/skills#override-skill-visibility-from-settings"
      },
      "uncertainties": [
        "token-window-to-character-ceiling",
        "fixed-environment-override-vs-fraction-precedence",
        "native-row-formatting",
        "usage-ordering",
        "complete-offline-discovery-coverage"
      ],
      "calibration": {
        "status": "unverified",
        "manualCandidate": "interactive /context",
        "requiredEvidenceFields": [
          "version",
          "model",
          "method",
          "timestamp",
          "observedMeasurements",
          "ceilingDerivation"
        ],
        "notes": [
          "claude doctor diagnoses installation/settings, not skill budget metrics.",
          "claude -p /doctor invokes a prompt-based skill and can run paid inference; it is not a local budget probe.",
          "Interactive /context is documented as reporting the fitted listing, but has not been validated by this research.",
          "Zero cost or output alone does not establish local diagnostics: authentication failure can also report zero.",
          "Any later calibration measurements must remain separate from documented defaults."
        ]
      }
    },
    {
      "harness": "opencode",
      "variant": "2.x",
      "default": true,
      "evidence": ["refresh-opencode-2.0.29-skill-listing", "refresh-opencode-2.0.29-skill-file"],
      "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/packages/core/src/skill/instructions.ts#L16-L95",
      "initialFields": ["id", "name", "description"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": "none",
        "fallback": null
      },
      "overflow": [],
      "allNamesRetained": true,
      "nameRetentionScope": "budget-overflow-only",
      "warning": "debug-log",
      "configuration": [
        "skills",
        "permissions",
        "agents.<id>.permissions",
        "metadata.opencode/autoinvoke",
        "disable-model-invocation"
      ],
      "uncertainties": [
        "No dedicated listing budget or shortening appears in the reviewed renderer; model/provider prompt limits remain separate.",
        "No large-catalog inference probe was run."
      ],
      "notes": [
        "Released 2.0.29 at 042d0832f5f3a73eaa039a58a7d565776f6d4290. Only permitted skills with a description and autoinvoke enabled enter the catalog.",
        "Entries are sorted by ID and include the full description; updates render changes or supersede the earlier list."
      ],
      "stability": "source-observed",
      "sourceRevision": "042d0832f5f3a73eaa039a58a7d565776f6d4290",
      "verifiedAt": "2026-10-15",
      "unknowns": ["No model or large-catalog runtime probe was run."]
    },
    {
      "harness": "cursor-agent",
      "variant": "catalog-recorded-evidence",
      "default": true,
      "evidence": ["skills-cursor-agent-cursor-com-docs-skills", "cursor-cli-changelog"],
      "reference": "https://cursor.com/docs/skills#how-skills-work",
      "initialFields": ["name", "description", "path"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": "none",
        "fallback": null
      },
      "overflow": ["shorten-descriptions"],
      "allNamesRetained": true,
      "nameRetentionScope": "budget-overflow-only",
      "warning": "user-warning",
      "configuration": ["paths", "disable-model-invocation"],
      "maxDescriptionCharacters": 1536,
      "uncertainties": [
        "Projection of existing dated reader-answer evidence; no new inference or large-catalog probe.",
        "Catalog visibility exclusions and provider context limits are independent of listing budget."
      ],
      "notes": [
        "At startup the agent is given the list of available skills with each skill's `description` and the path to its `SKILL.md`, and decides from the description when one is relevant. Skills with `paths` globs, or skills in a nested subdirectory, are listed only while the agent works with matching files. In CLI 2026.10.12 each description is cut to 1,536 characters before it is sent, there is no cap on the number of skills, and the list is ordered built-in, user, project, then plugin skills.",
        "Skills are not dropped for being numerous or long, but `/skills` shows a yellow warning count for skills that break the Agent Skills limits: a name over 64 characters or not lowercase-hyphen, a `name` that doesn't match the folder, a `description` over 1,024 characters, or a body over about 5,000 tokens. In CLI 2026.10.12 descriptions sent to the model are silently cut at 1,536 characters, and the `/` menu skips a `SKILL.md` larger than 1 MB.",
        "`description` is required unless the skill sets `disable-model-invocation: true`; a skill without one is reported as a parse error."
      ]
    },
    {
      "harness": "pi",
      "variant": "catalog-recorded-evidence",
      "default": true,
      "evidence": ["skills-pi-packages-coding-agent-src-core-skills-ts"],
      "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/skills.ts#L358-L388",
      "initialFields": ["name", "description", "path"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": "none",
        "fallback": null
      },
      "overflow": [],
      "allNamesRetained": true,
      "nameRetentionScope": "budget-overflow-only",
      "warning": "user-warning",
      "configuration": ["disable-model-invocation"],
      "uncertainties": [
        "Projection of existing dated reader-answer evidence; no new inference or large-catalog probe.",
        "Catalog visibility exclusions and provider context limits are independent of listing budget."
      ],
      "notes": [
        "Pi adds an `<available_skills>` block to the system prompt. Each skill gets its `name`, its full `description` and its `location`, which is the absolute path to `SKILL.md`. The block also tells the model to load a matching skill's file with `read` (or `bash`) and to resolve relative paths against the skill directory. There is no size budget for this list.",
        "Pi has no limit on the number of skills and does not truncate descriptions: every skill is listed with its full description. A description over 1024 characters, or a name that breaks the naming rules (more than 64 characters, or anything other than lowercase letters, digits and hyphens), only triggers a startup warning, and the skill still loads. A `SKILL.md` that has no `description` or cannot be parsed is not loaded.",
        "If neither `read` nor `bash` is enabled, the skills block is left out.",
        "Skills with `disable-model-invocation: true` are left out of the list."
      ],
      "stability": "source-observed",
      "sourceRevision": "06a466935536f8c9bcacb2d5efc0fc021be1bdff",
      "verifiedAt": "2026-10-15",
      "unknowns": ["Existing source inspection was projected; no new model probe was run."]
    },
    {
      "harness": "codex",
      "variant": "0.160.1-source-accounting",
      "default": false,
      "initialFields": ["name", "description", "path"],
      "bodyLoading": "on-selection",
      "budget": {
        "contextWindowFraction": 0.02,
        "fallback": {
          "unit": "characters",
          "value": 8000,
          "condition": "context-window-unknown"
        }
      },
      "overflow": ["shorten-descriptions", "may-omit-skills"],
      "allNamesRetained": false,
      "warning": "user-warning",
      "configuration": [
        "skills.max_context_tokens",
        "skills.include_instructions",
        "skills.bundled.enabled",
        "[[skills.config]] enabled"
      ],
      "evidence": ["codex-skill-listing-docs"],
      "reference": "https://learn.chatgpt.com/docs/build-skills#mainContent",
      "notes": [
        "Budget applies to initial listing, not the full selected SKILL.md.",
        "Historical nested accounting snapshot; select this variant to inspect the retained 0.160.1 source behaviour."
      ],
      "sourceBehavior": {
        "stability": "source-observed",
        "clientVersion": "0.160.1",
        "sourceRevision": "d27764b82f7118f674371e6d6e76271d9d606edb",
        "evidence": [
          "codex-skill-render-0.160.1-source",
          "codex-token-accounting-0.160.1-source",
          "codex-skill-policy-host-0.160.1-source",
          "codex-skill-policy-executor-0.160.1-source",
          "codex-skill-visible-catalog-0.160.1-source"
        ],
        "reference": "https://github.com/openai/codex/blob/d27764b82f7118f674371e6d6e76271d9d606edb/codex-rs/ext/skills/src/render.rs#L130",
        "budgetUnit": "approximate-tokens",
        "configurationOverride": {
          "field": "skills.max_context_tokens",
          "maximum": 10000
        },
        "accounting": "ceil-utf8-bytes-divided-by-four-per-row",
        "descriptionCap": 1024,
        "initialTruncation": {
          "prefixCharacters": 1021,
          "suffix": "..."
        },
        "overflowAllocation": "round-robin-description-prefixes",
        "overflowSuffix": "",
        "notes": [
          "Known-window default is floor(2% of context tokens), at least one; unknown-window fallback is 8,000 Unicode scalar characters. The positive configured token override takes priority and is capped at 10,000.",
          "Rows charge names, descriptions, locators/paths, separators and trailing newlines. Full rendered demand additionally includes shared listing overhead; allocator metadata cost is not necessarily the whole prompt cost. Alias tables/instructions and omission notices are accounted where applicable.",
          "Minimum rows that cannot fit may be omitted. Budget trimming does not append ellipses; the prior per-description cap does.",
          "Full demand before either description trimming stage must be distinguished from fitted listing demand. Neither is tokenizer or billing usage. These observations apply to this revision, not all Codex versions.",
          "At this revision, policy.allow_implicit_invocation: false in agents/openai.yaml hides host and executor skills from the model-visible catalog. PreparedSkillCatalog filters them out before row construction, alias planning and budget allocation, so their names, descriptions and paths incur no initial listing cost. Explicit $skill invocation remains available and loads instructions into conversation context outside the listing budget."
        ]
      }
    }
  ]
}