Skip to content

fix: shorten skill descriptions over the 1024-character operator limit - #158

Open
matallui wants to merge 1 commit into
mainfrom
fix/performance-skill-description-over-1024
Open

fix: shorten skill descriptions over the 1024-character operator limit#158
matallui wants to merge 1 commit into
mainfrom
fix/performance-skill-description-over-1024

Conversation

@matallui

@matallui matallui commented Sep 11, 2026

Copy link
Copy Markdown

Description

The pi coding agent rejects any skill whose description exceeds 1024 characters at startup. The base performance skill is 1078 characters, so every pi user sees this on launch and the skill never loads:

[Skill conflicts]
  auto (project) ~/git/metamask/metamask-mobile/.agents/skills/mms-performance/SKILL.md
    description exceeds 1024 characters (1078)

This PR:

  1. Trims the performance skill description from 1078 to 949 characters. Every trigger cue is kept — slow/laggy/janky surfaces, re-renders, memoization, FlashList, Reanimated, TTI, bundle size, .cpuprofile/Release Profiler analysis, render-regression tests, and the "not for" exclusions. The only cuts are filler ("at any stage", "and wanting to avoid perf pitfalls before building"), a redundant example filename, and a phrase duplicating the Release Profiler mention.
  2. Trims the swaps-cpu-profile-audit description from 1411 to 893 characters. It passed the old budget but was equally unloadable in pi.
  3. Lowers DESCRIPTION_MAX from 1536 to 1024 so yarn audit:skills blocks descriptions at least one operator cannot load, and updates the schema comment, README, CONTRIBUTING, and skill template accordingly.

On point 3: the schema comment asks contributors to "cite the operator and version before claiming any figure is externally imposed" — citation: pi coding agent v0.85.1, docs/skills.md: the description field is "Max 1024 chars", enforced with the error above. Claude Code still loads descriptions well over 1024 (as the old comment correctly noted), so 1024 is simply the strictest operator ceiling, exactly what CONTRIBUTING's "lowest limit across operators" already assumes.

Type of Change

  • New skill
  • Skill improvement/update
  • Bug fix
  • Documentation update
  • Other (please describe):

Skill Details (if adding a new skill)

N/A — existing skills only.

Checklist

  • I have read the CONTRIBUTING.md guidelines
  • My skill follows the SKILL_TEMPLATE.md format
  • I have tested this skill with an AI agent
  • My skill does not contain any secrets, private keys, or sensitive data
  • I have added appropriate documentation
  • My changes don't break existing skills

Testing

  • yarn audit:skills → 54 skill(s) checked, 0 errors (was 1 error after the budget change, 0 before — the swapped descriptions keep it at 0)
  • yarn test71/71 pass, including the docs-state/enforced-ceiling consistency test, which now asserts 1024
  • yarn lint:changelog → clean
  • Reproduced the original failure locally: pi v0.85.1 reports [Skill conflicts] description exceeds 1024 characters (1078) for the unmodified skill; after this change the description parses clean

The pi coding agent rejects any skill whose description exceeds 1024
characters at startup — the base performance skill (1078 chars) fails
with "[Skill conflicts] description exceeds 1024 characters (1078)"
and never loads.

- Trim the performance skill description from 1078 to 949 characters,
  keeping every trigger cue (slow/laggy/janky surfaces, re-renders,
  memoization, FlashList, Reanimated, TTI, bundle size, cpuprofile,
  render-regression tests, and the exclusions).
- Trim the swaps-cpu-profile-audit description from 1411 to 893
  characters, which the old budget allowed but pi users could not load.
- Lower DESCRIPTION_MAX to 1024, the strictest operator ceiling, so the
  linter blocks descriptions at least one operator cannot load, and
  update the schema comment, README, CONTRIBUTING, and skill template
  to state the new number and cite the operator.

Cite-the-operator evidence requested by the schema comment: pi coding
agent v0.85.1, docs/skills.md — description field: "Max 1024 chars".
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant