Repository navigation
Conversation
- Add ai/ with README, MANUAL_EVAL, 9 Claude skills, 5 Cursor mdc rules, AGENTS snippet - Add test/ai_skills_test.dart to align ai docs with lib sources - Document install paths in README; changelog Unreleased + issue VB10#88 - Fix README navigation examples to use context.route Made-with: Cursor
Tighten the YAML frontmatter `description:` of all nine kartal-* Agent
Skills with vanilla Flutter API names (EdgeInsets.symmetric,
BorderRadius.circular, MediaQuery.size.width, showDialog,
TextFormField validator, Navigator.of(context).pop, ...) and concrete
user phrasings ("60% of the screen width", "screenWidth * 0.6",
"blocking spinner", "go back", "around 24 logical pixels") so the
agent activates the right skill — and stays away from over-applying
helpers when a pixel-exact / design-system value is intended.
Body content (API tables, examples, gotchas, imports) is unchanged.
Made-with: Cursor
docs(skills): strengthen SKILL.md description triggers
There was a problem hiding this comment.
Code Review
This pull request introduces a set of Agent Skills for AI coding assistants, providing structured documentation for Kartal's extensions and utilities, while also updating the README and CHANGELOG. The review feedback identifies naming inconsistencies for the iterable.ext and launchMap extensions, suggests translating non-English terms for consistency, and points out a discrepancy in screen size breakpoint definitions compared to the existing README.
- skills/kartal-string-platform/SKILL.md: translate stray Turkish word
"muadili" to "equivalent of" in description for consistency with
the rest of the English documentation.
- README.md: fix four longstanding inaccuracies that drift from the
actual source:
- context.device.isSmallScreen / isMediumScreen / isLargeScreen
ranges were off by one bucket. Source of truth is
ResponsibilityConstants (300 / 600 / 900) plus the comparisons in
context_device_extension.dart, so isSmallScreen is 300 <= w < 600,
isMediumScreen is 600 <= w < 900, isLargeScreen is w >= 900.
- 'SAMPLE'.launchMap -> 'SAMPLE'.launchMaps to match the actual API
(string_share_mixin.dart: Future<bool> launchMaps({...})).
- Iterable Extension section: getter is `exts` (plural), not `ext`,
per IterableExtensions.exts in iterable_extension.dart, so the
prose and the [null,1].makeSafe() examples now use .exts.makeSafe()
and .exts.makeSafeCustom().
Source code is unchanged; this is documentation accuracy only.
Made-with: Cursor
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
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.
Summary
Adds nine
kartal-*Agent Skills underskills/(the ServerpodskillsCLI layout, installable withskills get --ide cursor/--ide claude/--ide codex) so AI coding agents pick the right kartal extension instead of writing vanilla Flutter boilerplate that re-implements features kartal already provides.Each skill maps a single area of kartal's surface (responsive UI, theming + navigation, string validation, string platform, async/future, popup loader, utilities) and ships with concrete API tables, before/after examples, gotchas, and a
kartal-do-not-overuseguardrail skill so the agent stays away from kartal helpers when a pixel-exact / design-system value is intended.Why
Without skills, agents reach for whatever Flutter API they remember — typically
MediaQuery.of(context).size, hand-rolledFuture.delayed+setStateloaders, rawRegExpemail checks, etc. — even on a project that already importspackage:kartal/kartal.dart. The skills give the agent a discoverable, kartal-shaped path for the same intent (context.sized.dynamicWidth,context.popupManager.showLoader,email.ext.isValidEmail, …) and a clear guardrail for when not to apply them.What's added
skills/kartal-overview/SKILL.md— load-first router that points at the right sibling skillskills/kartal-responsive-ui/SKILL.md—context.padding,context.sized,context.border,context.deviceskills/kartal-theming-navigation/SKILL.md—context.general,context.route,widget.extskills/kartal-string-validation/SKILL.md—string.extvalidators, color, JSONskills/kartal-string-platform/SKILL.md—string.extlaunchers, share, app/device metadataskills/kartal-async-future/SKILL.md—future.ext,map.ext,list.ext,iterable.extsskills/kartal-popup-loader/SKILL.md—context.popupManager.showLoader/hideLoaderskills/kartal-utilities/SKILL.md—MapsUtility,BundleDecoder,CustomLinkPreview,CustomLogger,HttpResult,DeviceUtility, small primitive extensionsskills/kartal-do-not-overuse/SKILL.md— guardrail (don't replace pixel-exact values, generated files, declarative routers, security checks)Plus install instructions in
README.mdand aCHANGELOG.mdentry.End-to-end test — same prompt, two fresh agent runs
A blank Flutter app with
kartal: ^…inpubspec.yamland the skills installed viaskills get --ide cursor. Same login-page prompt, identical user-visible strings ('Sign in','Welcome back','Email','Password','Login'). Both runs picked the right kartal APIs end-to-end.Run A —
login_page.dartRun B —
login_page2.dartSkills that activated in both runs
kartal-string-validationemail.ext.isValidEmailkartal-popup-loadercontext.popupManager.showLoader()/hideLoader()kartal-theming-navigationcontext.general.textTheme.headlineMedium,context.route.pop()kartal-responsive-uicontext.sized.dynamicWidth(0.6),context.border.lowBorderRadiuskartal-do-not-overuseEdgeInsets.symmetric(horizontal: 24)andBorderRadius.circular(8)vanilla — fixed-px / Material 8dp grid is correctly not force-converted to a kartal helperInter-run delta: Run A kept
BorderRadius.circular(8)(Material design-system token, allowed by the guardrail); Run B pickedcontext.border.lowBorderRadius. Both are valid —kartal-do-not-overusedeliberately does not force a conversion when a value looks like a design-system token.How to install in a project that uses kartal
Test plan
skills get --ide cursorwrites the nine skills to.cursor/skills/MediaQuery.of(context).size.width * 0.6, no manualshowDialogloader, no rawRegExpemail check)EdgeInsets.symmetric(horizontal: 24),BorderRadius.circular(8)) stay vanilla — guardrail intactdescription:and confirm no false-positive triggers on non-kartal Flutter projects