ChronicStone/nuxt-ui-tools / .agents/skills/nuxt-ui-tools-maintainer
nuxt-ui-tools-maintainer
VerifiedUse this skill for internal maintenance and feature work in the nuxt-ui-tools repository. It explains the repository operating model, exact placement rules, how runtime domains relate, how features should be structured and extended, how consumer skills must be maintained, and what to keep in sync when changing the library.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/change-workflow.md | markdown | 2.2 KB |
| references/consumer-skills.md | markdown | 2.2 KB |
| references/core-approach.md | markdown | 3.8 KB |
| references/dashboard-runtime.md | markdown | 27.8 KB |
| references/display-runtime.md | markdown | 3.5 KB |
| references/file-preview-runtime.md | markdown | 4.4 KB |
| references/form-runtime.md | markdown | 14.9 KB |
| references/placement-rules.md | markdown | 3.6 KB |
| references/query-state.md | markdown | 1.8 KB |
| references/shared-runtime.md | markdown | 809 B |
| references/spreadsheet-runtime.md | markdown | 6.0 KB |
| references/table-runtime.md | markdown | 8.0 KB |
references/core-approach.md
View on GitHub# Core Approach
This repository is trying to make both implementation and adoption easy.
That is the main lens for every design decision:
- internal architecture should reduce maintenance cost
- public APIs and consumer skills should reduce adoption cost
## What That Means In Practice
### For maintenance
The codebase should be:
- easy to scan
- easy to place new code into
- easy to refactor without fear
- organized by responsibility
- explicit about public vs internal surfaces
### For adoption
The package should be:
- schema-driven where that improves clarity
- inference-friendly
- example-driven in its consumer documentation
- consistent across features
- easy to explain without hidden setup knowledge
## The Core Tradeoff To Protect
The library should absorb complexity when doing so makes consumer usage simpler and more standard.
Good:
- complex internal normalization with a clean public schema API
- dynamic query-state machinery behind a small consumer surface
- config/registry-driven internals that preserve straightforward usage
Bad:
- awkward consumer typing to compensate for weak library inference
- consumer-side workaround patterns becoming "normal usage"
- leaking internal implementation details into the package surface
## Main Engineering Biases
- modularity over convenience
- composability over monoliths
- standard contracts over ad hoc branches
- config/registry-driven design whenever the domain has variants
- inference-first TypeScript
- lean reactivity
## Absolute Core Philosophy: Config / Registry Driven
This is not a stylistic preference.
It is a central design approach for this repository.
Use config/registry-driven design when a feature has:
- multiple kinds
- multiple modes
- multiple variants
- repeated branching behavior
Preferred direction:
- normalize the contract
- isolate per-kind behavior
- resolve through config/registry shape
Avoid:
- giant branching functions
- giant condition chains mixed with domain logic
- one file trying to know every variant
The filter preview split is the right kind of direction:
- shared normalized contract
- one implementation per filter kind
- orchestration consumes normalized outputs
Use this same approach for:
- filter kinds
- column kinds
- action variants
- layout-specific behavior
- future form / excel-import variant-heavy features
## Lean Reactivity Rule
Reactive architecture should be direct and explainable.
Prefer:
- one state abstraction that directly models the domain
- grouped state instead of many manually synchronized single refs
- computed values for real derivation only
- `shallowRef` for opaque instances and payloads
- VueUse when it removes boilerplate cleanly
Avoid:
- derived state wrapped in more derived state just to re-shape it
- extra computed bridges that exist only because the abstraction is too weak
- storing multiple representations of the same state
- preserving a slower architecture because it is already there
The current table/query-state integration is a known cleanup area.
Agents are encouraged to simplify it when touching it.
## Public Surface Rule
If a consumer-facing pattern is awkward, do not normalize the awkwardness.
Instead:
- improve the package abstraction
- improve inference
- improve consumer documentation/examples
The package should absorb complexity where it meaningfully reduces user burden.
That same rule applies to Nuxt auto-imports and component registration:
- keep them curated
- keep them explicit
- register only the APIs and components that are truly part of the intended public package story
In this repository, maintain those registrations in:
- `src/imports.ts` for public functions
- `src/components.ts` for public components
Keep both files organized by domain with clear comment blocks so agents can audit the public convenience surface quickly.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |