feat: add stac agent skills #444
Conversation
- Introduced new skills for scaffolding custom Stac widgets and actions, including templates and scripts for generating models and parsers. - Added a quickstart skill to initialize and validate Stac-enabled Flutter projects, with detailed workflows and required inputs. - Included necessary assets, references, and scripts to support the new functionalities.
📝 WalkthroughWalkthroughAdds a skills catalog and four new Stac skills (quickstart, screen-builder, custom-extensions, troubleshooter) including documentation, agent interface YAMLs, reference guides, scaffold templates, and multiple utility scripts; no existing runtime code modified. Changes
Sequence Diagram(s)(Skipped — changes are primarily docs/templates/scripts without a new multi-component runtime control flow that benefits from a sequence diagram.) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
No actionable comments were generated in the recent review. 🎉 🧹 Recent nitpick comments
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In `@skills/stac-custom-extensions/scripts/scaffold_custom_action.py`:
- Around line 73-78: The try/except around sequential writes can leave a
partially-created model_file if parser_file already exists; before calling
write_file for model_file or parser_file (in the scaffold logic that uses
write_file(render(...), args.force)), check existence of both model_file and
parser_file and only proceed if neither exists or args.force is true, or
alternatively implement a rollback: attempt to write model_file, and if writing
parser_file raises FileExistsError then delete/undo the written model_file and
re-raise/return the error. Update the same pattern in scaffold_custom_widget.py
to mirror this fix.
In `@skills/stac-custom-extensions/SKILL.md`:
- Around line 46-51: The SKILL.md Templates section lists four template files
that are missing: assets/templates/custom_widget.dart.tmpl,
custom_widget_parser.dart.tmpl, custom_action.dart.tmpl, and
custom_action_parser.dart.tmpl; either add these files with the expected
template content into the assets/templates/ directory (matching naming in
SKILL.md) or remove the four bullet entries from the Templates section in
SKILL.md so docs no longer reference non-existent files—update the README
consistently (modify the SKILL.md Templates block) and ensure any references to
these template names (custom_widget, custom_widget_parser, custom_action,
custom_action_parser) elsewhere are updated accordingly.
In `@skills/stac-quickstart/references/cli-workflow.md`:
- Around line 14-17: Update the step text that reads "Run `stac build` and
verify generated json files" to capitalize the acronym as "JSON" so it reads
"Run `stac build` and verify generated JSON files"; locate the string containing
"generated json files" (near the `stac build` step) and replace "json" with
"JSON".
In `@skills/stac-screen-builder/references/style-recipes.md`:
- Around line 10-12: Indent the two example lines so they are nested under the
"Text" bullet: change the items `StacThemeData.textTheme.titleLarge` and
`StacThemeData.textTheme.bodyMedium` to be indented (e.g., prefixed with two
spaces or a tab) beneath the "Use theme styles before hardcoded values:" list
entry so they render as sub-items of that bullet in the Markdown "Text" section.
In `@skills/stac-screen-builder/scripts/new_screen.py`:
- Around line 40-42: The current validation for screen_name (using
re.fullmatch(r"[a-z0-9_]+", screen_name)) allows names that start with a digit
or are only underscores which can produce invalid Dart identifiers when passed
to snake_to_camel; change the regex to require a leading lowercase letter (for
example re.fullmatch(r"[a-z][a-z0-9_]*", screen_name)) so screen names start
with a letter and only contain lowercase letters, digits, or underscores,
thereby preventing invalid Dart identifiers like "123Screen" or "__".
In `@skills/stac-troubleshooter/references/cache-debug.md`:
- Around line 12-17: The code block showing StacCloud.clearScreenCache and
StacCloud.clearAllCache should be rewritten to present them as alternative
options rather than sequential steps; update the example around clear cache to
show one snippet that labels the two calls as alternatives (e.g., a comment
"Clear a specific screen cache" before StacCloud.clearScreenCache('/home') and
"Or clear all cached screens" before StacCloud.clearAllCache()) so readers
understand they choose one or the other, referencing the methods
clearScreenCache and clearAllCache in the explanatory comments.
In `@skills/stac-troubleshooter/scripts/stac_doctor.py`:
- Around line 76-81: The code calls has_annotation(stac_dir) twice which
duplicates the expensive recursive scan; compute it once into a local variable
(e.g., found = has_annotation(stac_dir)) and then pass that variable into
add_result for the status and message decisions (keep references to
has_annotation, add_result, stac_dir, and the "stac-screen-annotation" key so
the change is easy to locate).
🧹 Nitpick comments (8)
skills/stac-screen-builder/scripts/new_theme_ref.py (1)
39-41: Consider handling a missing template file gracefully.If
theme_ref.dart.tmplis absent,read_text()raises an unhandledFileNotFoundErrorwith a raw traceback. A user-friendly[FAIL]message would be more consistent with the rest of the CLI output style.That said, this matches the pattern in sibling scripts (
new_screen.py), so it's fine to defer.♻️ Optional: wrap template read in a try/except
skill_root = Path(__file__).resolve().parents[1] template_path = skill_root / "assets" / "templates" / "theme_ref.dart.tmpl" - template = template_path.read_text(encoding="utf-8") + if not template_path.exists(): + print(f"[FAIL] Template not found: {template_path}") + return 1 + template = template_path.read_text(encoding="utf-8")skills/stac-custom-extensions/scripts/scaffold_custom_action.py (1)
12-37: Utility functions duplicated fromscaffold_custom_widget.py.
to_snake_case,render, andwrite_fileare copied verbatim from the widget scaffolding script. Consider extracting them into a shared module (e.g.,scripts/_shared.pyorscripts/utils.py) to keep the two scripts DRY.Not blocking — fine to defer if the skill scripts are intended to be standalone.
skills/stac-custom-extensions/references/converters-guide.md (1)
1-13: Consider adding usage examples for each converter.Each section currently has only a single sentence. Adding a brief annotation example (e.g.,
@DoubleConverter()on a field) would make this guide more actionable, especially for developers unfamiliar with the Stac converter pattern.skills/catalog.json (1)
1-1: Consider adding a schema version for future extensibility.As the catalog grows, a version field (e.g.,
{"version": 1, "skills": [...]}) would make it easier to evolve the format without breaking consumers. This is entirely optional for now.skills/stac-custom-extensions/scripts/check_parser_registration.py (1)
30-32: Substring match may produce false positives for parser class detection.
content.find(args.parser_class)matches any substring occurrence. For example,--parser-class StacFoowould matchStacFooBaror a comment mentioningStacFoo. Consider using a word-boundary regex for more precise detection.♻️ Suggested improvement
+ import re init_index = content.find("Stac.initialize(") - parser_index = content.find(args.parser_class) + parser_match = re.search(r'\b' + re.escape(args.parser_class) + r'\b', content) + parser_index = parser_match.start() if parser_match else -1skills/stac-troubleshooter/scripts/check_build_outputs.py (1)
30-30: Absolute--expected-dirsilently bypasses project root.If someone passes an absolute path for
--expected-dir, Python'sPath.__truediv__discards the left operand. Since the help text says "relative to project root," consider adding a guard.🛡️ Suggested guard
expected = root / args.expected_dir + if Path(args.expected_dir).is_absolute(): + print(f"[FAIL] --expected-dir must be relative: {args.expected_dir}") + return 1skills/stac-custom-extensions/scripts/scaffold_custom_widget.py (2)
12-35: Extract shared utilities to avoid duplication withscaffold_custom_action.py.
to_snake_case,render, andwrite_fileare identical copies fromscaffold_custom_action.py(lines 11-36). Consider extracting them into a shared module (e.g.,scripts/_scaffold_utils.py) to keep a single source of truth.
71-76: Partial write on parser failure leaves model file behind.If
write_file(model_file, ...)succeeds butwrite_file(parser_file, ...)raisesFileExistsError, the model file remains on disk with no cleanup. This could confuse a re-run without--force.🛡️ Suggested fix
try: write_file(model_file, render(model_template, mapping), args.force) write_file(parser_file, render(parser_template, mapping), args.force) except FileExistsError as exc: + # Clean up model file if parser write failed + if model_file.exists() and not parser_file.exists(): + model_file.unlink() print(f"[FAIL] {exc}") return 1
- Introduced new Dart templates for scaffolding custom Stac actions and widgets, including action parsers and widget parsers. - Each template includes JSON serialization support and basic structure for implementing action logic and widget rendering.
- Implemented a pre-check mechanism in `scaffold_custom_action.py` and `scaffold_custom_widget.py` to verify if output files already exist before writing, preventing partial file creation. - Enhanced error handling to manage potential `FileExistsError` exceptions more gracefully.
- Adjusted the indentation for theme style examples in the style-recipes.md file to ensure proper formatting and readability.
- Modified the regex for screen name validation to ensure it starts with a lowercase letter and contains only lowercase letters, digits, and underscores. This improves input validation for screen names.
- Added comments to clarify the usage of `clearScreenCache` and `clearAllCache` methods in the cache-debug.md file, improving readability and understanding for users.
- Refactored the STAC screen annotation check to store the result of `has_annotation(stac_dir)` in a variable before using it, improving code readability and efficiency.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In
`@skills/stac-custom-extensions/assets/templates/custom_action_parser.dart.tmpl`:
- Around line 1-3: Add an explicit import of dart:async so FutureOr is resolved:
update the template file that declares the custom action parser (the file
importing package:flutter/material.dart and stac_framework and
__FILE_BASENAME__.dart) to include import 'dart:async'; ensuring the FutureOr
type used in the generated code (the custom action parser) is available at
compile time.
🧹 Nitpick comments (1)
skills/stac-custom-extensions/scripts/scaffold_custom_widget.py (1)
12-35: Consider extracting shared helpers into a common module.
to_snake_case,render,write_file, and the validation regexes are duplicated verbatim betweenscaffold_custom_widget.pyandscaffold_custom_action.py. Extracting them into a shared utility module (e.g.,scaffold_utils.py) would reduce maintenance burden as more scaffold scripts are added.
skills/stac-custom-extensions/assets/templates/custom_action_parser.dart.tmpl
Show resolved
Hide resolved
1 participant
Description
Added new agent skills for Stac.
Related Issues
Closes #
Type of Change
Summary by CodeRabbit
New Features
Documentation
Tools