Repository navigation
Restore missing guidance in style-family AGENTS.md files - #84
Open
mattpodwysocki wants to merge 2 commits into
Open
mattpodwysocki wants to merge 2 commits into
mattpodwysocki wants to merge 2 commits into
Conversation
AGENTS.md ships standalone — README.md tells users to curl it into a project root — so anything absent from it is absent for that reader. In all three files the omissions were not detail trimmed for brevity, they were the substance of the skill, and the model filled the gaps with plausible generic advice. mapbox-style-quality never named a single one of its own MCP tools. validate_geojson_tool, validate_expression_tool, check_color_contrast_tool, compare_styles_tool and optimize_style_tool appear 16 times across SKILL.md and references and zero times in AGENTS.md, whose "Tools & Resources" section instead listed WebAIM, Coblis and Chrome DevTools. A guide to validating Mapbox styles shipped without the validators. Added a Validation Tools table, the pre-deploy order, what optimize_style_tool does and in what order, and the pre-commit/CI pipeline from references/ci-integration.md. mapbox-style-patterns omitted the route casing layer (a route is two layers, a wider casing behind a narrower line, or it reads as just another street), the pulse animation driven by setPaintProperty in a requestAnimationFrame loop, the match expression that colours delivery zones by status instead of one static fill, and the grayscale base map that a choropleth needs — including that water must be desaturated, since blue water competes directly with a red/blue political choropleth. mapbox-cartography omitted layer ordering entirely, so it could not say that user-generated content is topmost and POI symbols sit below it — a route the user is following must never be occluded by basemap POIs. Also added the POI zoom threshold: start at 12 for custom styles, 14 is late but acceptable, 10 is far too early. Agents-surface scores, n=5 per eval: mapbox-style-quality 46.2% -> 98.2% (#1 44->95, #2 44->100, #3 52->100) mapbox-style-patterns 62.2% -> 97.6% (#1 33->95, #2 59->97) mapbox-cartography 80.0% -> 97.1% (#1 56->100, #2 84->91) Every line added is drawn from the skill's own SKILL.md or references; no new guidance is introduced here. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
README.md:801tells users tocurla skill'sAGENTS.mdinto their project root for Codex and Copilot. It ships standalone, so whatever it omits is simply absent for that reader — and the model fills the hole with plausible generic advice rather than failing loudly.In all three files the omissions were the substance of the skill, not detail trimmed for brevity.
mapbox-style-quality— shipped without its own validatorsThe five MCP tools this skill exists to teach appear 16 times across
SKILL.mdandreferences/, and zero times inAGENTS.md. Its "Tools & Resources" section listed WebAIM, Coblis and Chrome DevTools instead. A guide to validating Mapbox styles shipped without the validators.Added a Validation Tools table, the pre-deploy order, what
optimize_style_tooldoes and in what sequence, and the pre-commit/CI pipeline that was sitting unused inreferences/ci-integration.md.mapbox-style-patterns— missing the patternspulseappears 7 times in references, 0 times inAGENTS.md. There is no built-in pulse; it needssetPaintPropertyin arequestAnimationFrameloop.matchexpression, not one static colour across every zone.mapbox-cartography— no layer ordering at allWith layer order absent, the file could not say that user-generated content is topmost and POI symbols sit below it. A route the user is actively following must never be occluded by basemap POIs, which is exactly what the model got wrong. Also added the POI zoom threshold: start at 12 for custom styles; 14 is late but acceptable; 10 is far too early.
Measured
Agents-surface,
--repeats=5:mapbox-style-qualitymapbox-style-patternsmapbox-cartographyPer eval: style-quality #1 44→95, #2 44→100, #3 52→100; style-patterns #1 33→95, #2 59→97; cartography #1 56→100, #2 84→91.
Every line added is drawn from the skill's own
SKILL.mdor references. No new guidance is introduced.Ordering
Branches from
main, independent of #80 and #83, mergeable in any order. The--surfaceand--repeatsflags used to measure this live in #80.🤖 Generated with Claude Code