@mahardikakdenie/agent-skills 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# AI Agent Skills CLI
+
+A Command Line Interface (CLI) tool to instantly inject curated AI Agent Skills into any project. This tool helps AI assistants (like Gemini CLI, Claude Code, or Cursor) understand your codebase conventions, patterns, and architectural rules from the moment they start working.
+
+## 🚀 Quick Start
+
+Inject the skills into your current project using `npx`:
+
+```bash
+npx @mahardikakdenie/agent-skills
+```
+
+This will create a `.agents/` directory in your project root containing all the skill files.
+
+## 📚 Available Skills
+
+When you run this tool, your project gains access to the following 13 skills:
+
+| Skill | Purpose |
+| :--- | :--- |
+| `monorepo-workspace` | Monorepo topology, package boundaries, and turbo CLI usage. |
+| `react-query` | TanStack Query v5 patterns and service layer architecture. |
+| `forms-validation` | react-hook-form v7 + zod validation patterns. |
+| `design-system` | Component building standards for `@repo/ui`. |
+| `impeccable` | Frontend interface design, UX review, and polish guidelines. |
+| `systematic-debugging` | Structured 4-phase root-cause investigation process. |
+| `turborepo` | Turborepo pipeline configuration and caching rules. |
+| `next-best-practices` | Next.js App Router, RSC, and data fetching patterns. |
+| `next-cache-components` | Next.js 16+ `use cache` and Partial Prerendering (PPR). |
+| `next-upgrade` | Workflow for upgrading Next.js version and running codemods. |
+| `vercel-react-best-practices` | 45 performance rules for React/Next.js from Vercel. |
+| `vercel-composition-patterns` | Advanced React composition and compound component patterns. |
+| `web-design-guidelines` | Accessibility and UX audit against Vercel's guidelines. |
+
+## 🛠️ How it Works
+
+The CLI copies the `.agents` folder from its template into your working directory. AI Agents are typically configured to ignore `node_modules`, but they *will* read configuration files in the project root. By placing the physical markdown files in your repo, you ensure:
+
+1. **Visibility**: AI can find and read the rules immediately.
+2. **Consistency**: Your AI assistant follows the same standards as the rest of your team.
+3. **Efficiency**: No need to explain your project's architecture to every new AI session.
+
+## 🤝 Contribution
+
+If you want to add or update a skill:
+1. Edit the files in `template/.agents/`.
+2. Bump the version in `package.json`.
+3. Publish the new version to NPM.
+
+---
+*Created with ❤️ for better AI-Human collaboration.*

package/bin/cli.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// Get current directory of the script
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Source is in the parent directory relative to 'bin/'
+const sourceDir = path.join(__dirname, '..', 'template', '.agents');
+const targetDir = path.join(process.cwd(), '.agents');
+
+console.log('🤖 Initializing AI Agent Skills...');
+
+if (!fs.existsSync(sourceDir)) {
+  console.error(`❌ Source directory not found: ${sourceDir}`);
+  process.exit(1);
+}
+
+try {
+  // Check if target directory already exists
+  if (fs.existsSync(targetDir)) {
+    console.log('⚠️  Target folder .agents already exists. Overwriting...');
+  }
+
+  // Copy recursive
+  fs.cpSync(sourceDir, targetDir, { recursive: true, force: true });
+
+  console.log('✅ Success! Folder .agents has been added to your project.');
+  console.log('💡 Your AI Assistant is now much smarter and understands your codebase standards!');
+} catch (error) {
+  console.error('❌ Failed to copy skills:', error.message);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mahardikakdenie/agent-skills",
+  "version": "1.0.0",
+  "description": "CLI to inject AI Agent Skills into your project",
+  "type": "module",
+  "bin": {
+    "init-skills": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "cli",
+    "npx",
+    "automation"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/template/.agents/README.md

@@ -0,0 +1,79 @@
+# 🤖 AI Agent Skills System
+
+The `.agents/` folder is the "brain" for AI assistants (such as Gemini CLI, Claude Code, or Cursor) operating within this repository. It contains structured instructions that enable AI to work consistently, correctly, and in accordance with the Engineering team's standards without needing to reverse-engineer the codebase repeatedly.
+
+## 📁 Directory Structure
+
+- **`skills/`**: Contains subdirectories for each specific capability (skill).
+  - **`SKILL.md`**: The main entry point for each skill.
+  - **`rules/`**, **`references/`**, **`templates/`**: Supporting documentation and code patterns.
+
+---
+
+## 📚 Skill Catalogue
+
+There are currently **13 skills** available. Use the relevant skill based on the task at hand:
+
+| Skill | When to Use |
+| :--- | :--- |
+| `monorepo-workspace` | When touching package boundaries, imports, or monorepo structure. |
+| `react-query` | Writing/reviewing `useQuery`, `useMutation` hooks, or API services. |
+| `forms-validation` | Working with forms (react-hook-form, zod). |
+| `design-system` | Building components in `packages/ui` or using Tailwind tokens. |
+| `impeccable` | Designing, reviewing UX/UI, or polishing frontend interfaces. |
+| `next-best-practices` | Writing App Router code (RSC, async APIs, metadata). |
+| `turborepo` | Configuring `turbo.json` or using the turbo CLI. |
+| `systematic-debugging` | Investigating bugs or test failures (before attempting a fix). |
+| `vercel-react-best-practices` | Performance optimization (waterfalls, bundle size, re-renders). |
+| `next-cache-components` | Using Next.js 16+ PPR features and `use cache`. |
+
+---
+
+## 🛠️ Usage Guide by Tool
+
+### 1. Gemini CLI / Antigravity
+Skills will be detected automatically. You can explicitly invoke specific skills using the `$` prefix:
+```bash
+$react-query — write a hook for the claims service
+$systematic-debugging — investigate why the build is failing
+```
+
+### 2. Claude Code
+Claude will automatically read the `CLAUDE.md` file which references this folder. You can also load skills manually:
+```bash
+/skill .agents/skills/react-query/SKILL.md
+```
+
+### 3. Cursor
+Cursor uses rules defined in `.cursor/rules/*.mdc` which reference the `.agents/skills/` directory.
+
+---
+
+## 💡 Best Practices
+
+- ✅ **Load Early**: Read the skill before starting the task, not halfway through.
+- ✅ **Load Multiple Skills**: If a task spans multiple concerns (e.g., Form + API), load both relevant skills.
+- ✅ **Trust the Skill**: Instructions here are project standards that override the AI's general training defaults.
+- ❌ **Don't Load Everything**: Loading too many irrelevant skills will add noise and confuse the AI.
+
+---
+
+## ➕ Adding a New Skill
+
+1. Create a directory: `.agents/skills/<skill-name>`
+2. Create `SKILL.md` with standard frontmatter:
+   ```markdown
+   ---
+   name: <skill-name>
+   version: 1.0.0
+   description: Use when...
+   tags: [tag1, tag2]
+   ---
+   # Skill Title
+   ...
+   ```
+3. Register it in the main catalogue inside `.agents/skills/README.md`.
+
+---
+
+*This system is designed to ensure the AI is not just a typing assistant, but a collaborative developer that deeply understands our architecture.*