Skip to content

Curate SKILL.md descriptions to fit default skill-listing budget #168

Description

@virtualian

Context

The v5.0.0 default skill set (45 skills) overflows the default skill-listing
budget on marrmini. Per /doctor output captured 2026-05-08
(reports/v5-comparison/marrmini-environment.txt, lines 86-119):

  • 45 skill descriptions are dropped from the welcome panel; the model
    receives skill names but no descriptions, degrading auto-routing.
  • 4 skills individually exceed the per-entry cap: ISA, BeCreative,
    Interview, and one more (identity not captured in /doctor output;
    needs confirmation against ~/.pai/skills/ runtime).
  • Aggregate would need ~7.7% of context vs the default 1%
    skillListingBudgetFraction.

Current workaround

The v5-0-0-plus overlay bumps skillListingBudgetFraction and
skillListingMaxDescChars in the Class-B settings.json merge (design
doc item #14) to accept the longer descriptions verbatim. Token-use
penalty: ~16k tokens/session ongoing per /doctor. Accepted trade-off
to keep v5 source unmodified.

Goal of this issue

  1. Identify the 4 over-cap skills definitively (read ~/.pai/skills/*/SKILL.md
    on marrmini; confirm the unnamed +1 alongside ISA, BeCreative, Interview).
  2. Trim the per-skill SKILL.md description fields so each fits the
    default per-entry cap.
  3. Trim aggregate so the 45-skill set fits the default
    skillListingBudgetFraction (1%).
  4. Once curated, reverse the overlay bump in settings.json Class-B
    merge and confirm /doctor no longer reports overflow.

Constraint

Don't modify v5-shipped skill source if avoidable — fork-side overrides
only. If the over-cap skills are v5-shipped (likely, since they appear
in the default 45-skill set), this issue may need to ship trimmed copies
via overlay rather than edit v5 originals in place. Decide that at
implementation time once the skill set is enumerated.

Refs

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions