AGENTS.md

1---
2name: ai-agents-skills
3description: "CLI framework for managing and distributing 50+ AI agent skills across 11 AI agents (3 dedicated + 8 universal)."
4license: "Apache 2.0"
5metadata:
6  version: "1.0"
7  skills:
8    - skill-creation
9    - agent-creation
10    - typescript
11    - nodejs
12    - nodejs-best-practices
13    - code-conventions
14    - critical-partner
15    - unit-testing
16    - jest
17    - brainstorming
18    - astro
19    - astro-best-practices
20    - tailwindcss
21    - css-best-practices
22    - a11y
23    - frontend-dev
24    - interface-design
25    - technical-communication
26    - reference-creation
27    - skill-sync
28    - systematic-debugging
29    - html
30    - css
31    - javascript
32    - english-writing
33    - code-review
34    - receiving-code-review
35    - writing-plans
36    - verification-protocol
37    - prompt-creation
38    - sharp-execution
39    - lean-output
40    - ship-branch
41    - grill-me
42    - context-handoff
43---
44 
45# AI Agents Skills Framework
46 
47CLI for creating, managing, and distributing AI agent skills across 11 AI agents. Local-first architecture with symlink-based installation, dependency resolution, and token-efficient model instructions.
48 
49## How to Use Skills (MANDATORY WORKFLOW)
50 
51This project has skills installed in your model's skills directory. Follow this protocol for ALL coding tasks:
52 
53### Step 1: Find the Trigger
54 
55Check the "Mandatory Skills" table below. Match your task to the "Trigger" column.
56 
57### Step 2: Read the Skill
58 
59Find your agent below and use the corresponding path:
60 
61| Agent | Skills path |
62|-------|------------|
63| Claude Code | `.claude/skills/{skill-name}/SKILL.md` |
64| Antigravity | `.agent/skills/{skill-name}/SKILL.md` |
65| OpenClaw | `skills/{skill-name}/SKILL.md` |
66| Amp, Cline, Codex, Cursor, Gemini CLI, GitHub Copilot, Kimi, OpenCode | `.agents/skills/{skill-name}/SKILL.md` |
67 
68**Shortcut:** All skill source files live at `skills/{skill-name}/SKILL.md` — if your agent can't resolve symlinks, read from there directly.
69 
70### Step 3: Read Dependencies
71 
72Every skill lists dependencies in its frontmatter (`metadata.skills`). Read each direct dependency before proceeding.
73 
74**Example:** `react` skill depends on: `a11y`, `typescript`, `javascript`, `architecture-patterns`
75 
76Read 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.
77 
78### Step 4: Apply Patterns
79 
80- Follow "Critical Patterns" marked with ✅ REQUIRED
81- Use "Decision Tree" for implementation choices
82- Reference inline code examples
83 
84### Example Workflow
85 
86**Task:** "Create TypeScript interface for User model"
87 
881. **Check table below** → Trigger: "TypeScript types/interfaces" → Skill: `typescript`
892. **Read:** `skills/typescript/SKILL.md` (or your agent's path from Step 2)
903. **Check frontmatter** → Dependencies: `javascript`
914. **Read dependency:**
92   - `skills/javascript/SKILL.md` (which depends on `code-conventions`)
935. **Apply patterns:** Use `interface` (not `type`), PascalCase names, export from `types/` directory
94 
95## Mandatory Skills
96 
97**Path:** Use the table in Step 2 above to find the correct path for your agent.
98 
99| Trigger                          | Skill            |
100| -------------------------------- | ---------------- |
101| Create or modify skills          | skill-creation   |
102| Create agent definitions         | agent-creation   |
103| Code review or improvements      | critical-partner |
104| Coding standards                 | code-conventions |
105| TypeScript code                  | typescript       |
106| Node.js / CLI development        | nodejs           |
107| Writing unit tests               | unit-testing     |
108| Jest test suite or config        | jest             |
109| Exploring ideas or approaches    | brainstorming    |
110| Astro pages, layouts, components | astro                  |
111| Tailwind utilities or styling    | tailwindcss            |
112| Accessibility or UI components   | a11y                   |
113| Frontend workflow or components  | frontend-dev           |
114| UI/UX decisions or design review | interface-design       |
115| Writing architecture or spike docs | tech-docs            |
116| Commit messages or documentation | technical-communication|
117| Creating reference files         | reference-creation     |
118| Syncing skills across models     | skill-sync             |
119| Debugging errors or root cause   | systematic-debugging   |
120| HTML markup or structure         | html                   |
121| CSS properties or animations     | css                    |
122| JavaScript patterns or scripts   | javascript             |
123| Writing skill content in English | english-writing        |
124| Formal code review checklist     | code-review            |
125| Processing incoming review feedback | receiving-code-review |
126| Planning implementation tasks    | writing-plans          |
127| Verifying task completion        | verification-protocol  |
128| Creating model prompt files      | prompt-creation        |
129| Agent overthinking or hesitation | sharp-execution        |
130| Minimize response tokens         | lean-output            |
131| Shipping or closing a branch     | ship-branch            |
132| Clarify requirements before acting | grill-me             |
133| Summarize session for new chat   | context-handoff        |
134| Auth, JWT, OAuth, password hashing | authentication       |
135| Dockerfiles or containerization  | docker                 |
136| GraphQL schemas or resolvers     | graphql                |
137| Documenting a design system      | design-system-spec     |
138| React code quality review        | react-best-practices   |
139| Astro site quality review        | astro-best-practices   |
140| CSS architecture review          | css-best-practices     |
141| Node.js service quality review   | nodejs-best-practices  |
142 
143## Skills Reference
144 
14550+ skills organized by category (exact count shown as nearest lower multiple of 50: 50+, 100+, 150+, etc.):
146 
147- **Frameworks:** React, Next.js, Astro, Express, Nest, Hono, React Native, Expo
148- **Best Practices:** React Best Practices, Astro Best Practices, CSS Best Practices, Node.js Best Practices
149- **Testing:** Jest, Playwright, React Testing Library, React Native Testing Library, E2E Testing, Unit Testing, Testing Strategy
150- **Standards:** TypeScript, JavaScript, HTML, CSS, TailwindCSS, A11y
151- **Backend & Infrastructure:** Node.js, Express, Nest, Hono, Bun, Backend Development, Authentication, Docker, GraphQL
152- **Web:** Web Performance, Web SEO, Design System Spec
153- **Build Tools:** Vite, Webpack
154- **Libraries:** MUI, AG Grid, Redux Toolkit, Stagehand
155- **Quality & Architecture:** Code Conventions, Code Quality, Form Validation, Critical Partner, Code Refactoring
156- **Architecture Patterns:** Architecture Patterns, SOLID, Clean Architecture, Domain-Driven Design, Hexagonal Architecture, Result Pattern, DRY Principle, Mediator Pattern, Sidecar Pattern, Composition Pattern, Circuit Breaker Pattern, State Machines Pattern, Screaming Architecture
157- **Documentation:** Tech Docs
158- **Behavioral:** English Writing, Technical Communication, Humanizer, Frontend Development, Brainstorming, Systematic Debugging, Interface Design, Writing Plans, Code Review, Receiving Code Review, Verification Protocol, Plan Execution, Subagent Orchestration, Sharp Execution, Lean Output, Ship Branch, Grill Me, Context Handoff
159- **Meta:** Skill Creation, Agent Creation, Reference Creation, Prompt Creation, Skill Sync
160 
161## Project Structure
162 
163```
164ai-agents-skills/
165├── skills/                # 50+ skill definitions (SKILL.md format) - SOURCE OF TRUTH
166│   ├── react/
167│   │   ├── SKILL.md
168│   │   └── references/    # Progressive disclosure for complex skills
169│   ├── typescript/
170│   │   └── SKILL.md
171│   └── ...
172├── .agents/skills/        # Canonical symlinks → skills/ (universal: 8 agents read here natively)
173│   ├── react/            → ../../skills/react/
174│   ├── typescript/       → ../../skills/typescript/
175│   └── ...
176├── .claude/skills/        # Claude Code symlinks → .agents/skills/
177│   ├── react/            → ../../.agents/skills/react/
178│   └── typescript/       → ../../.agents/skills/typescript/
179├── .agent/skills/         # Antigravity symlinks → .agents/skills/
180├── presets/               # Project Starter Preset (AGENTS.md + skills bundle)
181├── src/                   # TypeScript CLI source
182│   ├── commands/          # CLI commands (local, add, remove, sync, validate, list)
183│   ├── core/              # Dependency resolver, installer, skill parser
184│   └── utils/             # Logger, YAML parser, instruction generator
185├── templates/             # Model instruction templates
186├── website/               # Astro SSG skill catalog website
187│   ├── src/
188│   │   ├── content/       # Content collections (skills, references)
189│   │   ├── layouts/       # BaseLayout, SkillLayout
190│   │   ├── pages/         # Index, getting-started, skills/[name], references/[ref]
191│   │   ├── components/    # SkillMeta, ReferenceSidebar, TableOfContents, etc.
192│   │   └── styles/        # global.css (Tailwind v4 CSS-based config)
193│   ├── astro.config.mjs
194│   └── package.json
195└── AGENTS.md             # This file
196```
197 
198**IMPORTANT FOR LLMs:** When reading skills, you will encounter a 3-layer symlink structure:
199 
2001. **Source of truth:** `skills/<skill-name>/SKILL.md` (real files, always read from here)
2012. **Canonical layer:** `.agents/skills/<skill-name>/` → `skills/<skill-name>/` (shared symlinks)
2023. **Model-specific layer:** `.claude/skills/` and `.agent/skills/` → `.agents/skills/` (dedicated model symlinks)
203 
204**How to access skills:**
205 
206- **Preferred:** Read directly from `skills/<skill-name>/SKILL.md` (bypasses symlinks — always works)
207- **Alternative:** Use your agent's path from Step 2 if your IDE resolves symlinks automatically
208- **If symlinks fail:** All real skill files are in `skills/` directory
209 
210### Skills Storage Architecture
211 
212**Why 3 layers?**
213 
2141. **Layer 1 (skills/):** Single source of truth — edit once, affects all agents
2152. **Layer 2 (.agents/skills/):** Canonical shared location — 8 universal agents read here natively
2163. **Layer 3 (.claude/skills/, .agent/skills/):** Dedicated model symlinks for Claude Code and Antigravity
217 
218**Benefits:**
219 
220- **Zero duplication:** Skills stored once, available to all 11 agents
221- **Always up-to-date:** Changes propagate instantly (symlinks reference same files)
222- **Token-efficient:** Models read only the skills they need
223 
224**Example flow:**
225 
226```
227User edits: skills/react/SKILL.md
228      ↓
229Symlink: .agents/skills/react/ → skills/react/
230      ↓
231Universal agents (Amp, Cline, Codex, Cursor, Gemini, Copilot, Kimi, OpenCode)
232      read: .agents/skills/react/ directly
233      ↓
234Dedicated agents get additional symlinks:
235  .claude/skills/react/ → .agents/skills/react/   (Claude Code)
236  .agent/skills/react/  → .agents/skills/react/   (Antigravity)
237      ↓
238OpenClaw reads: skills/react/ directly (project root, no symlink needed)
239      ↓
240All 11 agents see updated react skill instantly
241```
242 
243## Workflows
244 
245### Create a Skill
246 
2471. Read `skills/skill-creation/SKILL.md`
2482. `mkdir skills/{name}` + copy SKILL-TEMPLATE.md
2493. Write SKILL.md with frontmatter and sections
2504. Validate: `npx ai-agents-skills validate --skill {name}`
2515. Install: `npx ai-agents-skills local`
252 
253### Create an Agent
254 
2551. Read `skills/agent-creation/SKILL.md`
2562. Gather context (9 questions)
2573. Create `presets/{project-name}/AGENTS.md`
2584. Validate all referenced skills exist
259 
260### Update Website
261 
262The website (`website/`) is an Astro SSG site that auto-renders skills from `skills/` via content collections.
263 
2641. Read `skills/astro/SKILL.md` and `skills/tailwindcss/SKILL.md`
2652. Pages live in `website/src/pages/` — skills rendered via `[name]/index.astro`
2663. Layouts: `BaseLayout.astro` (shell), `SkillLayout.astro` (two-column with sidebar)
2674. Components: `SkillMeta`, `ReferenceSidebar`, `TableOfContents`, `Breadcrumb`
2685. Styles: Tailwind v4 via `@theme` in `website/src/styles/global.css` (no `tailwind.config.*`)
2696. Build: `cd website && npm run build` — deploys via GitHub Actions on push to `main`
270 
271**Key conventions:**
272- Reference sidebar uses `{slug, title}[]` — titles extracted from H1 of each reference file
273- Skills H1: topic name only, no "Skill" suffix (e.g., `# React`, not `# React Skill`)
274- `---` separator required before every `##` section except the first
275 
276### Install Skills
277 
278```bash
279npx ai-agents-skills local                    # Install to all detected models
280npx ai-agents-skills local --models claude     # Install to specific model
281npx ai-agents-skills validate --all            # Validate all skills
282```
283 
284## Policies
285 
286- **Explicit dependencies:** Skills declare all their dependencies in `metadata.skills` — no hidden auto-includes
287- **Dependency resolution:** Auto-resolve with cycle detection and topological sort
288- **Two-tier model architecture:**
289  - **Dedicated models** — require their own skills directory:
290    - Claude Code (`.claude/skills/`), Antigravity (`.agent/skills/`), OpenClaw (`skills/`)
291  - **Universal models** — read `.agents/skills/` natively, no extra directory needed:
292    - Amp, Cline, Codex, Cursor, Gemini CLI, GitHub Copilot, Kimi, OpenCode
293- **Symlink architecture:** 3-layer structure for zero duplication:
294  - **Layer 1:** `skills/` (source of truth — real files; also OpenClaw's native path)
295  - **Layer 2:** `.agents/skills/` → `skills/` (canonical shared symlinks — universal coverage)
296  - **Layer 3:** `.claude/skills/` and `.agent/skills/` → `.agents/skills/` (dedicated model symlinks)
297  - **Individual skill symlinks:** Each skill gets its own symlink (NOT directory-level)
298  - **Instant propagation:** Changes to source files visible to all agents immediately
299- **Auto-generated instructions:** Each model gets an instruction file listing all installed skills with their metadata
300- **Dependency-safe removal:** `remove` command validates dependencies before removing skills
301- **11 agents supported:** 3 dedicated (Claude Code, Antigravity, OpenClaw) + 8 universal (Amp, Cline, Codex, Cursor, Gemini CLI, GitHub Copilot, Kimi, OpenCode)
302 
303## Git & Release Workflow
304 
305### Branching
306 
307- **`main`** — production, always stable, tagged releases only
308- **`development`** — integration branch, all feature work merges here first
309- Feature branches off `development`, never off `main`
310 
311### Commit Strategy
312 
313- **Use skill:** `technical-communication` for all commit messages
314- **Format:** single line, imperative, no co-author
315- **Examples:**
316  - `fix: show interactive selector when all AGENTS.md skills installed`
317  - `feat: add PostHog analytics for web and CLI`
318  - `chore: update OG image to match logo`
319- **Group by feature:** separate commits per logical change, never batch unrelated changes
320 
321### Merge to Main (Squash)
322 
323Merges from `development` → `main` use **squash merge**. The squash commit message format encodes the release type and triggers the auto-release pipeline:
324 
325```
326release(patch|minor|major): {brief summary of what's in the squash}
327```
328 
329Examples:
330- `release(patch): telemetry + PostHog analytics + CI release pipeline`
331- `release(minor): preset system overhaul + new skills`
332 
333### Versioning & Release
334 
335Versions follow **semver**: `MAJOR.MINOR.PATCH`
336 
337| Change type | Squash merge prefix | Example |
338|---|---|---|
339| Bug fix, small improvement | `release(patch): ...` | 1.6.0 → 1.6.1 |
340| New feature, backwards-compatible | `release(minor): ...` | 1.6.0 → 1.7.0 |
341| Breaking change | `release(major): ...` | 1.6.0 → 2.0.0 |
342 
343**Release flow:**
3441. Work on `development`, commit with single-line messages
3452. Squash merge to `main` with a `release(patch|minor|major): {summary}` message
3463. `auto-release.yml` detects the prefix on push to `main`, runs `npm version <type>`, and pushes the version commit + tag — no manual command needed
3474. `auto-release.yml` bumps the version, builds, publishes to npm, updates the README badge, and syncs back to `development` — all in one pipeline
348 
349**Tags always go on `main`**, never on `development`.
350 
351## CodeGraph
352 
353This project has a CodeGraph MCP server (`codegraph_*` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
354 
355### When to prefer codegraph over native search
356 
357Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
358 
359| Question | Tool |
360|---|---|
361| "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
362| "What calls function Y?" | `codegraph_callers` |
363| "What does Y call?" | `codegraph_callees` |
364| "What would break if I changed Z?" | `codegraph_impact` |
365| "Show me Y's signature / source / docstring" | `codegraph_node` |
366| "Give me focused context for a task/area" | `codegraph_context` |
367| "Survey an unfamiliar module/topic" | `codegraph_explore` |
368| "What files exist under path/" | `codegraph_files` |
369| "Is the index healthy?" | `codegraph_status` |
370 
371### Rules of thumb
372 
373- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
374- **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
375- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
376- **`codegraph_explore` is the heavy hitter** for unfamiliar areas — returns full source from all relevant files in one call, but is token-heavy.
377- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
378 
379### If `.codegraph/` doesn't exist
380 
381The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run `codegraph init -i` to build the index?"*
382 
383## References
384 
385- [AGENTS.md Spec](https://agents.md/)
386- [Agent Skills](https://agentskills.io/)
387