Skip to content

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

Open
matallui wants to merge 2 commits into
mainfrom
fix/performance-skill-description-over-1024
Open

matallui wants to merge 2 commits 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 (v0.85.1) warns about any skill whose description exceeds 1024 characters at startup. The base performance skill is 1078 characters, so every pi user sees this on launch:

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

The skill still loads — pi treats this as a validation warning, not a rejection (its Validation docs: over-limit descriptions "produce warnings but still load the skill"; only missing/empty descriptions and malformed SKILL.md files fail to load). But the warning names a file we ship, so our descriptions should fit the limit.

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 warning-worthy in pi.
  3. Lowers DESCRIPTION_MAX from 1536 to 1024 so yarn audit:skills blocks descriptions that trip operator warnings, 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", and the Validation section states over-limit descriptions "produce warnings but still load the skill". So 1024 is the largest value that trips no operator's validation — 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 → 63 skill(s) checked, 0 errors (96 warnings are pre-existing on main)
  • yarn test71/71 pass, including the docs-state/enforced-ceiling consistency test, which asserts 1024
  • yarn lint:changelog → clean
  • Verified against the pi v0.85.1 source: over-length descriptions are pushed as type: "warning" diagnostics and the skill object is still returned and loaded; the [Skill conflicts] banner is warning-colored. Reproduced locally: pi reports [Skill conflicts] description exceeds 1024 characters (1078) for the unmodified skill while it remains loaded; after this change the description parses clean.

@matallui
matallui force-pushed the fix/performance-skill-description-over-1024 branch 2 times, most recently from 57f11b1 to e885ac9 Compare September 15, 2026 15:26
The pi coding agent (v0.85.1) warns about any skill whose description
exceeds 1024 characters at startup — the base performance skill (1078
chars) triggers "[Skill conflicts] description exceeds 1024 characters
(1078)" on every launch. The skill still loads (pi treats this as a
validation warning, not a rejection), but the warning names a file we
ship, so keep our descriptions within the limit.

- 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 also tripped the warning in pi.
- Lower DESCRIPTION_MAX to 1024, the strictest operator's validation
  limit, so the linter blocks descriptions that trip operator warnings,
  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 — Validation section: over-limit
descriptions "produce warnings but still load the skill".
…-description-over-1024

* origin/main:
  feat: add navigation skill with MetaMask Mobile overlay (#148)
  feat: add feature-flags skill with MetaMask Mobile overlay (#147)
  feat: add analytics skill with MetaMask Mobile overlay (#140)
  feat: Adds `observability` domain with Sentry, Tempo, telemetry cost control skills (#76)
  refactor(perps): review skill composes the perps library instead of carrying knowledge copies (#159)

# Conflicts:
#	README.md
@matallui
matallui force-pushed the fix/performance-skill-description-over-1024 branch from e885ac9 to 9bb8561 Compare September 15, 2026 15:27
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