Skip to content

docs(skills): shorten and front-load the skill descriptions - #75

Open
JonMUnity wants to merge 8 commits into
mainfrom
docs/shorten-skill-descriptions
Open

JonMUnity wants to merge 8 commits into
mainfrom
docs/shorten-skill-descriptions

Conversation

@JonMUnity

@JonMUnity JonMUnity commented Sep 18, 2026 •

Copy link
Copy Markdown

For this PR, I tried to shorten the skill descriptions to make the plugin more performant for Codex.

This branch was created from the branch used to create this PR: #74.

Here is a table comparing the character limit changes. "Before" is what's on main now and "After" is the current branch.

Skill Before After
generate-editor-search-query 1009 214
setup-vivox-voice-chat 968 207
levelplay-unity-integration 967 271
implement-in-app-purchases 927 282
optimize-text-mesh-pro 698 224
ui 666 204
unity-cli 647 286
build-live-game 641 246
physics-3d-collision 640 232
new-unity-project 604 201
tilemap-ruletile-createfromsegment 592 208
migrate-birp-to-urp 550 198
unity-package-management 536 241
manage-sprite-atlas 528 187
setup-multiplayer-services 499 218
ui-imgui 495 183
optimize-audio 418 241
audio-setup-mixers 417 222
optimize-web 394 207
initialize-ai-navigation 394 200
tilemap-ruletile-createempty 383 213
sprite-segment-3x3grid 348 196
localization 339 203
sprite-editor 294 157
validate-urp-render-graph-renderer-feature 283 200
ui-uitk 264 200
urp-postprocessing 238 178
ui-ugui 213 186
tilemap-palette-create 211 148
shader-graph-create-custom-node 171 159
2d-pixel-perfect 133 220
Total 15,467 6,532

@JonMUnity
JonMUnity requested a review from a team as a code owner September 18, 2026 19:15
@JonMUnity
JonMUnity requested a review from ziyiunity September 18, 2026 19:15
jthorborg
jthorborg previously approved these changes Sep 21, 2026

@jthorborg jthorborg left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Audio LGTM regardless, but could be more aggressively trimmed.

Having authored some of these original skills and seeing the description evolved, I'm curious as to why we made those changes in the first place, or if we can somehow measure agent performance impact of doing this.

Comment thread skills/audio-setup-mixers/SKILL.md Outdated
Comment thread skills/optimize-audio/SKILL.md Outdated
chris-addison
chris-addison previously approved these changes Sep 21, 2026
leoyaikUnity
leoyaikUnity previously approved these changes Sep 22, 2026

@leoyaikUnity leoyaikUnity left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sprite Editor skill LGTM

Comment thread skills/levelplay-unity-integration/SKILL.md Outdated
Comment thread skills/optimize-text-mesh-pro/SKILL.md Outdated
Comment thread skills/physics-3d-collision/SKILL.md Outdated
Comment thread skills/manage-sprite-atlas/SKILL.md Outdated
@JonMUnity

JonMUnity commented Sep 22, 2026 •

Copy link
Copy Markdown
Author

Audio LGTM regardless, but could be more aggressively trimmed.

I'm going to try and trim all of them a bit more aggressively, since we're still far from where want to be.

Having authored some of these original skills and seeing the description evolved, I'm curious as to why we made those changes in the first place, or if we can somehow measure agent performance impact of doing this.

These changes are being done primarily to satisfy a requirement from Codex. Codex will drop skills at a point when character limits exceed a threshhold. Apart from that, we're broadly trying to work towards aligning skill descriptions to our rules here: https://internal.docs.unity.com/en-us/docs-quality/documentation/skill-model. This guidance was written mostly as a synthesis over Anthropic's guidance, so the field is a bit muddied now with these requirements from Codex.

@JonMUnity

Copy link
Copy Markdown
Author

Apologies to my reviewers. I made even more judicious reductions to try and fit Codex requirements.

Conflicts were description-only in four skills. main's side is the
folded copy of the pre-shortening text (from #74, the squash of this
branch's own YAML-quoting fix), so this branch's shortened
descriptions win in all four.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
karljj1
karljj1 previously approved these changes Sep 23, 2026

@karljj1 karljj1 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving skills/localization/SKILL.md

Comment thread skills/unity-cli/SKILL.md
Comment thread skills/ui/SKILL.md Outdated
Comment thread skills/tilemap-ruletile-createfromsegment/SKILL.md Outdated
Comment thread skills/physics-3d-collision/SKILL.md Outdated

@Antoine-Lassauzay Antoine-Lassauzay left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved on behalf of the UI team, but I agree there is a subtle change of meaning to the UI routing skill that may lead agents to bypass it.

@JonMUnity
JonMUnity dismissed stale reviews from Antoine-Lassauzay and karljj1 via b864c2c September 23, 2026 18:23

@leoyaikUnity leoyaikUnity left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve for 2D

@JonMUnity

Copy link
Copy Markdown
Author

Approved on behalf of the UI team, but I agree there is a subtle change of meaning to the UI routing skill that may lead agents to bypass it.

@Antoine-Lassauzay I changed the description for the routing table in response to yours and @ziyiunity's feedback.

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.

8 participants