About project-architecture
project-architecture is a skill for guiding structural and UI changes in Next.js and Astro apps. It sets framework-specific guardrails for server/client boundaries, design conventions, data states, testing, and completion reporting.
Key features
- 01Framework detection before changes
- 02Server-first rendering guidance
- 03Framework documentation checks
- 04Design and component conventions
- 05Explicit data display states
- 06Risk-based tests and checklist
Use cases
- 01Planning a UI or layout change
- 02Changing state flow or data display
- 03Adjusting server/client boundaries
- 04Reviewing implementation before completion
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/project-architecturein Claude Code to confirm it loaded.
Bundled filesreferences/astro.mdreferences/next.md
Details
From the project READMEProject Architecture Guardrails
Activation Contract
Load this skill before changing UI, layout, component structure, state flow, theming, data display, or the server/client boundary of a Next.js or Astro app.
Hard Rules
- Detect the framework from the project before acting; never assume it.
- Keep rendering server-first. Add client-side code only when the interaction cannot work without it, and keep that surface as small as possible.
- Read the installed framework's own docs before changing framework APIs or project structure.
- Follow
DESIGN.mdfor visual and UX decisions when it exists. - Build from existing shadcn primitives and semantic tokens before writing custom markup or styles; load
shadcn-component-boundarieswhen it is installed. - Make loading, empty, and error states explicit for every data display.
- Add tests proportional to risk, using the test tooling the project already has.
Decision Gates
| Project signal | Framework | Guidance |
|---|---|---|
next in package.json dependencies, or a next.config.* file | Next.js | references/next.md |
astro in package.json dependencies, or an astro.config.* file | Astro | references/astro.md |
| Both or neither | Unknown | Stop and ask which app the change targets |
Execution Steps
- Read
package.jsonand list the root config files to detect the framework. - Load the matching reference and apply its boundary rules.
- Search existing components, routes, and styles before creating new ones.
- Implement the change with the smallest client-side surface that works.
- Answer the pre-close checklist, then load
project-min-evaluationwhen it is installed, or run the project's quality scripts.
Pre-close checklist:
- Did the change add unnecessary client-side surface?
- Does it follow
DESIGN.md? - Are loading, empty, and error states explicit?
Output Contract
Report the detected framework, every server/client boundary added or moved (with its reason), and the checklist answers.
References
- references/next.md — Next.js server/client boundary rules.
- references/astro.md — Astro island boundary rules.
Comments
Markdown supported