create-agent-skills 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# Agent Skills CLI
+
+CLI tool to install Agent Skills for AI coding assistants.
+
+## Installation
+
+```bash
+npx create-agent-skills
+```
+
+Or install globally:
+
+```bash
+npm install -g create-agent-skills
+```
+
+## Usage
+
+Run the CLI and follow the interactive prompts:
+
+```bash
+npx create-agent-skills
+```
+
+### Options
+
+1. **Install Location**
+   - `Workspace` - `.agent/skills/` (project-specific)
+   - `Global` - `~/.gemini/antigravity/skills/` (all projects)
+
+2. **Skill Selection**
+   - Use `Space` to toggle skills
+   - Use `a` to toggle all
+   - Use `i` to invert selection
+   - Press `Enter` to confirm
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `code-review` | Reviews code for bugs, style, and security issues |
+| `create-agent-skill` | Helps create new skills following guidelines |
+| `documentation` | Creates clear READMEs, API docs, and comments |
+| `testing` | Helps write unit, integration, and E2E tests |
+
+## Creating New Skills
+
+See [SKILL_GUIDELINES.md](./SKILL_GUIDELINES.md) for the complete guide.
+
+### Quick Start
+
+```bash
+mkdir -p .agent/skills/my-skill
+```
+
+Create `SKILL.md` with:
+
+```markdown
+---
+name: my-skill
+description: What this skill does. Use when...
+---
+
+# My Skill
+
+Instructions for the agent...
+```
+
+### Folder Structure
+
+```
+.agent/skills/<skill-name>/
+├── SKILL.md          # Main instructions (REQUIRED)
+├── scripts/          # Helper scripts (optional)
+├── examples/         # Reference implementations (optional)
+└── resources/        # Templates and other assets (optional)
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/Nghi-NV/create-agent-skills.git
+cd create-agent-skills
+
+# Install dependencies
+npm install
+
+# Run locally
+node bin/cli.js
+```
+
+## License
+
+MIT

package/SKILL_GUIDELINES.md

@@ -0,0 +1,339 @@
+# Agent Skills Guidelines
+
+Standard guidelines for creating skills for AI Agents. All skills must follow these rules.
+
+---
+
+## 📁 Required Folder Structure
+
+```
+.agent/skills/<skill-name>/
+├── SKILL.md          # Main instructions (REQUIRED)
+├── scripts/          # Helper scripts (optional)
+├── examples/         # Reference implementations (optional)
+└── resources/        # Templates and other assets (optional)
+```
+
+### Naming Rules
+
+| Element | Rule | Example |
+|---------|------|---------|
+| Folder name | lowercase, hyphens | `code-review`, `unit-testing` |
+| SKILL.md | MUST be uppercase | `SKILL.md` (not `skill.md`) |
+| Scripts | lowercase, hyphens | `run-tests.sh`, `validate.js` |
+
+### When to Use External Files
+
+> [!TIP]
+> If your SKILL.md becomes too long (>500 lines), split content into the appropriate folders and link to them.
+
+**Use `examples/` folder when:**
+- You have multiple code examples
+- Examples are complete, runnable files
+- Examples need syntax highlighting that's hard to read inline
+
+**Use `scripts/` folder when:**
+- You have helper scripts the agent should run
+- Scripts are reusable utilities
+
+**Use `resources/` folder when:**
+- You have templates, config files, or other assets
+- You have images or diagrams
+
+#### Linking to External Files
+
+In your SKILL.md, link to external files using relative paths:
+
+```markdown
+## Examples
+
+For complete examples, see:
+- [Basic Usage](./examples/basic-usage.js) - Simple getting started example
+- [Advanced Patterns](./examples/advanced-patterns.js) - Complex use cases
+- [Error Handling](./examples/error-handling.js) - How to handle edge cases
+
+## Scripts
+
+Run the validation script:
+\`\`\`bash
+./scripts/validate.sh --help
+\`\`\`
+
+See [validate.sh](./scripts/validate.sh) for implementation details.
+
+## Templates
+
+Use the provided templates:
+- [Component Template](./resources/component-template.tsx)
+- [Test Template](./resources/test-template.spec.ts)
+```
+
+#### Example Folder Structure (Large Skill)
+
+```
+.agent/skills/react-components/
+├── SKILL.md                          # Main instructions, links to examples
+├── scripts/
+│   ├── generate-component.sh         # Script to scaffold components
+│   └── validate-props.js             # Prop validation utility
+├── examples/
+│   ├── basic-button.tsx              # Simple button example
+│   ├── form-with-validation.tsx      # Form handling example
+│   ├── data-fetching.tsx             # API integration example
+│   └── README.md                     # Examples index/overview
+└── resources/
+    ├── component-template.tsx        # Starter template
+    ├── test-template.spec.ts         # Test file template
+    └── styles-template.module.css    # CSS module template
+```
+
+---
+
+## 📄 SKILL.md Format
+
+### YAML Frontmatter (Required)
+
+Every SKILL.md MUST start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: Clear description of what this skill does. Use when you need to do X or Y.
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | No | Unique identifier (lowercase, hyphens). Defaults to folder name |
+| `description` | **YES** | What the skill does and when to use it. Agent sees this first |
+
+> [!IMPORTANT]
+> **Description is the most important field!** The agent uses the description to decide whether to use the skill. Be clear and specific.
+
+### Standard Content Structure
+
+```markdown
+---
+name: my-skill
+description: Helps with a specific task. Use when you need to do X or Y.
+---
+
+# Skill Name
+
+Brief overview of what this skill provides.
+
+## When to Use This Skill
+
+- Use this when...
+- This is helpful for...
+- Consider this skill if...
+
+## Prerequisites
+
+- Required tools/dependencies
+- Environment setup needed
+
+## How to Use
+
+Step-by-step guidance, conventions, and patterns the agent should follow.
+
+### Step 1: [Action Name]
+
+Detailed instructions...
+
+### Step 2: [Action Name]
+
+Detailed instructions...
+
+## Decision Tree
+
+Use this section for complex skills with multiple paths:
+
+```
+Is X true?
+├── YES → Do A
+│   └── Then do B
+└── NO → Do C
+    └── Then do D
+```
+
+## Examples
+
+### Example 1: [Scenario]
+
+\`\`\`bash
+# Example command or code
+\`\`\`
+
+## Best Practices
+
+- Practice 1
+- Practice 2
+
+## Common Pitfalls
+
+- Pitfall 1: How to avoid
+- Pitfall 2: How to avoid
+```
+
+---
+
+## ✅ Validation Checklist
+
+Before publishing a skill, verify:
+
+### Structure
+- [ ] Folder name is lowercase with hyphens
+- [ ] Has `SKILL.md` file (correctly capitalized)
+- [ ] YAML frontmatter has `description`
+
+### Content
+- [ ] Description is clear and specific (not generic)
+- [ ] Has "When to Use" section
+- [ ] Has "How to Use" section with specific steps
+- [ ] Examples are realistic and runnable
+
+### Best Practices
+- [ ] Skill focuses on one specific task
+- [ ] No overlap with other skills
+- [ ] Scripts have `--help` option
+- [ ] Decision tree for complex logic
+
+---
+
+## 🎯 Best Practices
+
+### 1. Keep Skills Focused
+
+```diff
+- ❌ skill: "do-everything-for-project"
++ ✅ skill: "code-review"
++ ✅ skill: "unit-testing"
++ ✅ skill: "documentation"
+```
+
+### 2. Write Clear Descriptions
+
+```diff
+- ❌ description: "Helps with code"
++ ✅ description: "Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality."
+```
+
+### 3. Use Scripts as Black Boxes
+
+Encourage the agent to run `script --help` instead of reading source code:
+
+```markdown
+## Available Scripts
+
+Run `./scripts/validate.sh --help` to see all options.
+Do NOT read the script source directly.
+```
+
+### 4. Include Decision Trees
+
+For complex skills:
+
+```markdown
+## Decision Tree
+
+What type of test?
+├── Unit Test → Use `jest` with mocking
+├── Integration Test → Use `supertest` for API
+└── E2E Test → Use `playwright` or `cypress`
+```
+
+### 5. Provide Real Examples
+
+```markdown
+## Examples
+
+### Reviewing a Pull Request
+
+1. Check out the PR branch
+2. Run linting: `npm run lint`
+3. Run tests: `npm test`
+4. Review changes file by file
+```
+
+---
+
+## 📝 Starter Template
+
+Copy this template to start a new skill:
+
+```markdown
+---
+name: my-new-skill
+description: [Clear, specific description. Include keywords for discovery.]
+---
+
+# [Skill Name]
+
+[1-2 sentence overview]
+
+## When to Use This Skill
+
+- Use when [specific situation 1]
+- Use when [specific situation 2]
+- NOT for [exclusion case]
+
+## Prerequisites
+
+- [Required tool/setup 1]
+- [Required tool/setup 2]
+
+## How to Use
+
+### Step 1: [First Action]
+
+[Detailed instructions]
+
+### Step 2: [Second Action]
+
+[Detailed instructions]
+
+## Examples
+
+### [Example Scenario]
+
+\`\`\`bash
+# Example commands
+\`\`\`
+
+## Best Practices
+
+- [Practice 1]
+- [Practice 2]
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| [Problem 1] | [Fix 1] |
+| [Problem 2] | [Fix 2] |
+```
+
+---
+
+## 🗂️ Skill Locations
+
+| Location | Scope | Use Case |
+|----------|-------|----------|
+| `<workspace>/.agent/skills/` | Workspace-specific | Team workflows, project conventions |
+| `~/.gemini/antigravity/skills/` | Global (all workspaces) | Personal utilities, general tools |
+
+---
+
+## 📚 Optional Sections
+
+Add these sections when needed:
+
+| Section | When to Include |
+|---------|-----------------|
+| `## Prerequisites` | When setup is required |
+| `## Decision Tree` | When there are multiple paths/options |
+| `## Scripts` | When skill has helper scripts |
+| `## Configuration` | When there are config options |
+| `## Troubleshooting` | When there are common issues |
+| `## Related Skills` | When related to other skills |

package/bin/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+const ora = require('ora');
+const path = require('path');
+const fs = require('fs-extra');
+const { getAvailableSkills, installSkills, getInstallPath } = require('../lib/installer');
+
+const BANNER = `
+╔═══════════════════════════════════════════════════════════════╗
+║                                                               ║
+║   ${chalk.cyan.bold('🚀 Agent Skills Installer')}                                 ║
+║                                                               ║
+║   Install skills to extend your AI agent's capabilities       ║
+║                                                               ║
+╚═══════════════════════════════════════════════════════════════╝
+`;
+
+async function main() {
+  console.log(BANNER);
+
+  const skills = getAvailableSkills();
+
+  if (skills.length === 0) {
+    console.log(chalk.yellow('⚠️  No skills available to install.'));
+    process.exit(0);
+  }
+
+  // Step 1: Choose installation location
+  const { installLocation } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'installLocation',
+      message: 'Where do you want to install skills?',
+      choices: [
+        {
+          name: `${chalk.green('Workspace')} (.agent/skills/) - Project-specific skills`,
+          value: 'workspace'
+        },
+        {
+          name: `${chalk.blue('Global')} (~/.gemini/antigravity/skills/) - Available everywhere`,
+          value: 'global'
+        }
+      ]
+    }
+  ]);
+
+  // Step 2: Select skills with checkbox
+  const { selectedSkillNames } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selectedSkillNames',
+      message: 'Select skills to install:',
+      choices: skills.map(skill => ({
+        name: skill.name,
+        value: skill.name,
+        checked: true
+      })),
+      pageSize: 15,
+      validate: (answer) => {
+        if (answer.length === 0) {
+          return 'Please select at least one skill.';
+        }
+        return true;
+      }
+    }
+  ]);
+
+  const selectedSkills = skills.filter(s => selectedSkillNames.includes(s.name));
+
+  // Step 3: Confirm installation
+  console.log('');
+  console.log(chalk.bold('📦 Skills to install:'));
+  selectedSkills.forEach(skill => {
+    console.log(`   ${chalk.green('•')} ${skill.name}`);
+  });
+  console.log('');
+
+  const installPath = getInstallPath(installLocation);
+  console.log(chalk.dim(`📁 Install location: ${installPath}`));
+  console.log('');
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Proceed with installation?',
+      default: true
+    }
+  ]);
+
+  if (!confirm) {
+    console.log(chalk.yellow('Installation cancelled.'));
+    process.exit(0);
+  }
+
+  // Step 4: Install skills
+  const spinner = ora('Installing skills...').start();
+
+  try {
+    const results = await installSkills(selectedSkills, installLocation);
+
+    spinner.succeed(chalk.green('Installation complete!'));
+    console.log('');
+
+    // Show results
+    results.forEach(result => {
+      if (result.success) {
+        console.log(`   ${chalk.green('✔')} ${result.name} installed successfully`);
+        if (result.structure && result.structure.length > 1) {
+          console.log(chalk.dim(`      └── ${result.structure.join(', ')}`));
+        }
+      } else {
+        console.log(`   ${chalk.red('✖')} ${result.name} failed: ${result.error}`);
+      }
+    });
+
+    console.log('');
+    console.log(chalk.cyan('🎉 Skills are ready to use!'));
+    console.log(chalk.dim(`   Location: ${installPath}`));
+
+  } catch (error) {
+    spinner.fail(chalk.red('Installation failed'));
+    console.error(chalk.red(error.message));
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error(chalk.red('Error:'), error.message);
+  process.exit(1);
+});

package/lib/index.js

@@ -0,0 +1,5 @@
+const installer = require('./installer');
+
+module.exports = {
+  ...installer
+};