AGENTS.md

1---
2name: beta-template
3description: "Static site generation assistant for an Astro project. Astro 5 SSG, Tailwind 4, minimal runtime JS, client island architecture, semantic HTML."
4metadata:
5  version: "1.0"
6  skills:
7    - typescript
8    - javascript
9    - astro
10    - vite
11    - tailwindcss
12    - react
13    - html
14    - a11y
15    - code-conventions
16    - technical-communication
17    - critical-partner
18    - interface-design
19    - frontend-dev
20---
21 
22# Beta Template Agent
23 
24## Purpose
25 
26Primary development assistant for an Astro static site. Ensures static-first rendering, minimal runtime JavaScript, Astro 5 and Tailwind 4 best practices, semantic HTML, and accessibility standards.
27 
28## How to Use Skills (MANDATORY WORKFLOW)
29 
30This project has skills installed in your model's skills directory. Follow this protocol for ALL coding tasks:
31 
32### Step 1: Find the Trigger
33 
34Check the "Skills Reference" table below. Match your task to the "Trigger" column.
35 
36### Step 2: Read the Skill
37 
38**Path format:** `.{model}/skills/{skill-name}/SKILL.md`
39 
40Replace `{model}` with your coding agent:
41 
42- **Cursor:** `.cursor/skills/typescript/SKILL.md`
43- **Claude:** `.claude/skills/typescript/SKILL.md`
44- **Copilot:** `.github/skills/typescript/SKILL.md`
45- **Gemini:** `.gemini/skills/typescript/SKILL.md`
46- **Codex:** `.codex/skills/typescript/SKILL.md`
47 
48### Step 3: Read Dependencies
49 
50Every skill lists dependencies in its frontmatter (`metadata.skills`). Read each direct dependency before proceeding.
51 
52**Example:** `react` skill depends on: `a11y`, `typescript`, `javascript`, `architecture-patterns`
53 
54Read these 4 direct dependencies. Dependencies are resolved transitively - when you read `typescript`, you'll see it depends on `javascript`, which depends on `code-conventions`. The dependency chain ensures you have all required context.
55 
56### Step 4: Apply Patterns
57 
58- Follow "Critical Patterns" marked with ✅ REQUIRED
59- Use "Decision Tree" for implementation choices
60- Reference inline code examples
61 
62### Example Workflow
63 
64**Task:** "Create TypeScript interface for User model"
65 
661. **Check table below** → Trigger: "TypeScript types/interfaces" → Skill: `typescript`
672. **Read:** `.{model}/skills/typescript/SKILL.md`
683. **Check frontmatter** → Dependencies: `javascript`
694. **Read dependency:**
70   - `.{model}/skills/javascript/SKILL.md` (which depends on `code-conventions`)
715. **Apply patterns:** Use `interface` (not `type`), PascalCase names, export from `types/` directory
72 
73## Skills Reference
74 
75**Path format:** `.{model}/skills/{skill-name}/SKILL.md` (see Step 2 above)
76 
77| Trigger                       | Skill                   |
78| ----------------------------- | ----------------------- |
79| TypeScript types/interfaces   | typescript              |
80| JavaScript (ES2020+)          | javascript              |
81| Astro pages/components        | astro                   |
82| Vite build config             | vite                    |
83| Tailwind utility classes      | tailwindcss             |
84| React client islands          | react                   |
85| Semantic HTML                 | html                    |
86| Accessibility                 | a11y                    |
87| Commit messages, PRs, docs    | technical-communication |
88| Code review                   | critical-partner        |
89| Coding standards              | code-conventions             |
90| UI/UX design, flows, visual   | interface-design        |
91| Frontend development workflow | frontend-dev            |
92 
93## Project Structure & Skills Storage
94 
95**IMPORTANT FOR LLMs:** Skills use a 3-layer symlink structure:
96 
97```
98your-project/
99├── .agents/skills/        # Canonical symlinks to framework skills/ (shared across models)
100│   ├── astro/            → ../../skills/astro/
101│   ├── typescript/       → ../../skills/typescript/
102│   └── ...
103├── .claude/skills/        # Claude-specific symlinks to .agents/skills/
104│   ├── astro/            → ../../.agents/skills/astro/
105│   └── typescript/       → ../../.agents/skills/typescript/
106├── .cursor/skills/        # Cursor-specific symlinks to .agents/skills/
107├── .github/skills/        # Copilot-specific symlinks to .agents/skills/
108├── .gemini/skills/        # Gemini-specific symlinks to .agents/skills/
109├── .codex/skills/         # Codex-specific symlinks to .agents/skills/
110└── AGENTS.md             # This file
111```
112 
113**How to access skills:**
114 
115- **Preferred:** Read from `.{model}/skills/<skill-name>/SKILL.md` (your model's directory)
116- **If symlinks fail:** Skills are stored in the ai-agents-skills framework installation (referenced via symlinks)
117- **Real files location:** All source skills are in the framework's `skills/` directory
118 
119**Why 3 layers?**
120 
1211. **Layer 1 (framework skills/):** Source of truth maintained by framework
1222. **Layer 2 (.agents/skills/):** Canonical shared location in your project
1233. **Layer 3 (.{model}/skills/):** Model-specific access for your AI assistant
124 
125**Benefits:**
126 
127- **Zero duplication:** Skills installed once, available to all 5 AI models
128- **Always up-to-date:** Changes propagate instantly via symlinks
129- **Token-efficient:** Your AI reads only the skills it needs
130 
131## Supported Stack
132 
133- **Project type:** Astro 5.14.5 static site generator (SSG)
134- **Languages:** TypeScript 5.9.3, JavaScript (ES2020+)
135- **Build:** Astro 5.14.5, Vite (latest)
136- **Styling:** TailwindCSS 4.1.14, @tailwindcss/vite 4.1.14
137- **Client interactivity:** React 18+ (client:load islands only, minimal)
138- **Principles:** Static-first, minimal runtime JS, semantic HTML, accessibility
139 
140## Workflows
141 
142### Feature Development
143 
1441. Gather requirements, clarify static vs dynamic content needs
1452. Design page architecture with Astro components (.astro files)
1463. Implement with build-time data fetching in frontmatter
1474. Style with Tailwind 4 utility classes and @theme tokens
1485. Add client islands (React) ONLY when interactivity required
1496. Use appropriate directives (client:load, client:visible, client:idle)
1507. Ensure semantic HTML and accessibility, document changes, request review
151 
152### Code Review
153 
1541. Verify static-first approach (no unnecessary client-side JS)
1552. Check Astro directive usage, Tailwind 4 theme tokens
1563. Review semantic HTML, accessibility, TypeScript strict mode
1574. Confirm build-time data fetching (no runtime API calls in static pages)
158 
159## Policies
160 
161**Typing:** strict mode, explicit types for frontmatter variables, jsx: react-jsx
162 
163**Astro directives:**
164 
165- Prefer build-time computation in component frontmatter
166- Use `define:vars` for frontmatter→script, `set:html` for trusted HTML
167- Use `client:load` for React hydration, avoid `client:only` unless necessary
168- No global JS imports in markup; keep scripts isolated
169 
170**Tailwind 4 theming:**
171 
172- Define tokens in `@theme` block (--color-_, --font-_, --spacing-\*, etc.)
173- No deprecated --tw-\* prefixes; use official Tailwind 4 variable names
174- Semantic token names (--color-primary, --color-accent)
175 
176**Accessibility:** Semantic elements (`<header>`, `<main>`, `<nav>`, `<section>`), proper heading hierarchy, labeled forms, descriptive alt text, ARIA only when semantic HTML insufficient
177 
178**Versions:**
179 
180- Exact: Astro 5.14.5, TailwindCSS 4.1.14, TypeScript 5.9.3
181- Ranges: Astro >=5.0 <6.0, Tailwind >=4.0 <5.0, TS >=5.0 <6.0
182 
183**Performance:** Static rendering first, client islands sparingly, minimal bundle size, excellent Lighthouse scores
184