ma-agents 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to AI Agent Skills
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Ways to Contribute
+
+1. **Add New Skills** - Create useful skills for AI agents
+2. **Add Agent Support** - Add support for new AI coding agents
+3. **Improve Documentation** - Enhance README and guides
+4. **Fix Bugs** - Report and fix issues
+5. **Suggest Features** - Propose new features
+
+## Getting Started
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd ai-agent-skills
+
+# Install dependencies
+npm install
+
+# Test the CLI
+node bin/cli.js
+```
+
+## Adding a New Skill
+
+1. Create a directory in `skills/` with your skill name (kebab-case)
+2. Add `skill.json` with metadata
+3. Create at least `generic.md` template
+4. Optionally create agent-specific templates
+5. Test your skill with multiple agents
+
+See [README.md](README.md#how-to-add-a-new-skill) for detailed instructions.
+
+## Adding a New Agent
+
+1. Edit `lib/agents.js`
+2. Add your agent configuration to the `agents` array
+3. Test installation with existing skills
+
+See [README.md](README.md#how-to-add-a-new-agent) for detailed instructions.
+
+## Code Style
+
+- Use 2 spaces for indentation
+- Follow existing code structure
+- Add comments for complex logic
+- Keep functions focused and small
+
+## Testing
+
+Before submitting:
+
+1. Test the CLI works: `node bin/cli.js`
+2. Test skill installation for multiple agents
+3. Verify all paths work on your OS
+4. Check that new skills appear in the list
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/my-feature`
+3. Make your changes
+4. Commit with clear messages: `git commit -m "feat: add new skill"`
+5. Push to your fork: `git push origin feature/my-feature`
+6. Open a Pull Request
+
+## Pull Request Guidelines
+
+- Provide clear description of changes
+- Reference any related issues
+- Include testing steps
+- Update documentation if needed
+
+## Skill Quality Guidelines
+
+When contributing skills:
+
+- **Clear Instructions**: Provide step-by-step guidance for the AI
+- **Good Examples**: Include example interactions
+- **Appropriate Scope**: Skill should have a focused purpose
+- **Well-Documented**: Include usage instructions
+- **Tested**: Verify it works with at least one agent
+
+## Questions?
+
+Feel free to open an issue for:
+- Questions about contributing
+- Clarification on guidelines
+- Feature discussions
+
+Thank you for contributing!

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 AI Agent Skills
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QUICK_START.md

@@ -0,0 +1,148 @@
+# Quick Start Guide
+
+Get started with AI Agent Skills in 2 minutes!
+
+## Installation (Users)
+
+No installation needed! Just run:
+
+```bash
+npx ai-agent-skills
+```
+
+## Using the CLI
+
+1. **Run the tool:**
+   ```bash
+   npx ai-agent-skills
+   ```
+
+2. **Select "Install a skill"**
+
+3. **Choose a skill:**
+   - Code Review
+   - Test Generator
+   - Commit Message Generator
+
+4. **Select your AI agents:**
+   - Claude Code
+   - Gemini
+   - Copilot
+   - Kilocode
+   - Cline
+   - Cursor
+
+5. **Choose installation path:**
+   - Press Enter for default path
+   - Or type a custom path
+
+6. **Done!** The skill is now available in your selected agents.
+
+## Quick Examples
+
+### List all available skills
+```bash
+npx ai-agent-skills
+# Select: List available skills
+```
+
+### List supported agents
+```bash
+npx ai-agent-skills
+# Select: List supported agents
+```
+
+### Install a skill
+```bash
+npx ai-agent-skills
+# Select: Install a skill
+# Choose: code-review
+# Select agents: claude-code, cline
+# Path: (press Enter for default)
+```
+
+## Using Installed Skills
+
+After installation, use the skills in your AI agent:
+
+**Claude Code:**
+```bash
+claude-code
+> /code-review
+```
+
+**Other Agents:**
+Check your agent's documentation for how to invoke custom skills or prompts.
+
+## Development Quick Start
+
+Want to add your own skills or agents?
+
+### Add a Skill (5 minutes)
+
+1. Create directory:
+   ```bash
+   mkdir skills/my-skill
+   ```
+
+2. Create `skill.json`:
+   ```json
+   {
+     "name": "My Skill",
+     "description": "What it does",
+     "version": "1.0.0",
+     "author": "You",
+     "tags": ["tag1"]
+   }
+   ```
+
+3. Create `generic.md`:
+   ```markdown
+   # My Skill
+
+   Instructions for the AI agent...
+   ```
+
+4. Test it:
+   ```bash
+   node bin/cli.js
+   ```
+
+### Add an Agent (3 minutes)
+
+1. Edit `lib/agents.js`
+
+2. Add to `agents` array:
+   ```javascript
+   {
+     id: 'my-agent',
+     name: 'My Agent',
+     description: 'My AI Agent',
+     getSkillsPath: () => {
+       // Return path based on OS
+     },
+     fileExtension: '.md',
+     template: 'generic'
+   }
+   ```
+
+3. Test it:
+   ```bash
+   node bin/cli.js
+   ```
+
+## Need Help?
+
+- Read the full [README.md](README.md)
+- Check [CONTRIBUTING.md](CONTRIBUTING.md)
+- See [examples/](examples/) for code examples
+- Open an issue on GitHub
+
+## What's Next?
+
+- Browse existing skills in `skills/`
+- Read detailed guides in [README.md](README.md)
+- Contribute your own skills!
+- Add support for your favorite AI agent
+
+Happy coding with AI agents! 🤖

package/README.md

@@ -0,0 +1,420 @@
+# AI Agent Skills
+
+A universal NPX tool to install skills for AI coding agents including Claude Code, Gemini, Copilot, Kilocode, Cline, and Cursor.
+
+## Features
+
+- 🤖 Support for multiple AI coding agents
+- 📦 Easy skill installation via NPX
+- 🔧 Extensible architecture for adding new agents
+- 📝 Simple skill creation system
+- 🎯 Interactive CLI for user-friendly installation
+
+## Supported Agents
+
+- **Claude Code** - Anthropic's Claude Code CLI
+- **Google Gemini** - Google Gemini Code Assist
+- **GitHub Copilot** - GitHub Copilot Agent Mode
+- **Kilocode** - Kilocode AI Assistant
+- **Cline** - Cline AI Assistant (VSCode Extension)
+- **Cursor** - Cursor AI Editor
+
+## Installation
+
+No installation required! Use directly with NPX:
+
+```bash
+npx ai-agent-skills
+```
+
+## Usage
+
+### Interactive Mode
+
+Simply run the command and follow the prompts:
+
+```bash
+npx ai-agent-skills
+```
+
+You'll be able to:
+1. Choose an action (install skill, list skills, list agents)
+2. Select a skill to install
+3. Choose which agents to install for
+4. Specify a custom installation path (optional)
+
+### Available Skills
+
+The package comes with example skills:
+
+- **Code Review** - Comprehensive code review following best practices
+- **Test Generator** - Generate unit and integration tests
+- **Commit Message Generator** - Create conventional commit messages
+
+## Project Structure
+
+```
+ai-agent-skills/
+├── bin/
+│   └── cli.js              # CLI entry point
+├── lib/
+│   ├── agents.js           # Agent configurations
+│   └── installer.js        # Installation logic
+├── skills/
+│   ├── code-review/
+│   │   ├── skill.json      # Skill metadata
+│   │   ├── claude-code.md  # Claude Code template
+│   │   ├── generic.md      # Generic template
+│   │   └── cline.md        # Cline-specific template
+│   ├── test-generator/
+│   │   ├── skill.json
+│   │   └── ...
+│   └── commit-message/
+│       ├── skill.json
+│       └── generic.md
+├── package.json
+└── README.md
+```
+
+## How to Add a New Skill
+
+Adding a new skill is straightforward. Follow these steps:
+
+### 1. Create Skill Directory
+
+Create a new directory under `skills/` with your skill name (use kebab-case):
+
+```bash
+mkdir skills/my-awesome-skill
+```
+
+### 2. Create Skill Metadata
+
+Create a `skill.json` file in your skill directory:
+
+```json
+{
+  "name": "My Awesome Skill",
+  "description": "Brief description of what this skill does",
+  "version": "1.0.0",
+  "author": "Your Name",
+  "tags": ["tag1", "tag2", "tag3"]
+}
+```
+
+**Fields:**
+- `name`: Display name for the skill
+- `description`: Short description (shown in skill list)
+- `version`: Semantic version number
+- `author`: Your name or organization
+- `tags`: Array of tags for categorization
+
+### 3. Create Skill Templates
+
+Create at least one template file. You can create:
+
+#### Generic Template (recommended)
+`generic.md` - Works for all agents
+
+```markdown
+# My Awesome Skill
+
+Brief description of the skill.
+
+## Instructions
+
+Step-by-step instructions for the AI agent...
+
+## Examples
+
+Example interactions...
+```
+
+#### Agent-Specific Templates (optional)
+Create specialized templates for specific agents:
+
+- `claude-code.md` - Claude Code specific
+- `cline.md` - Cline specific
+- `generic.md` - Fallback for all other agents
+
+**Template Naming Convention:**
+- Use the agent's `template` field from [lib/agents.js](lib/agents.js)
+- Add the agent's `fileExtension` (usually `.md`)
+
+### 4. Template Content Guidelines
+
+Your skill template should include:
+
+```markdown
+# Skill Name
+
+## Description
+Clear explanation of what the skill does
+
+## Usage
+How to invoke or use this skill
+
+## Instructions
+Detailed instructions for the AI agent:
+1. Step 1
+2. Step 2
+3. ...
+
+## Examples
+Example interactions showing:
+- User input
+- Expected AI behavior
+
+## Output Format (if applicable)
+Template or structure for the AI's output
+```
+
+### 5. Test Your Skill
+
+After creating your skill, test it:
+
+```bash
+npx ai-agent-skills
+# Select "List available skills" to verify it appears
+# Then install it to test
+```
+
+### Example: Creating a "Documentation Generator" Skill
+
+```bash
+# 1. Create directory
+mkdir skills/doc-generator
+
+# 2. Create skill.json
+cat > skills/doc-generator/skill.json << 'EOF'
+{
+  "name": "Documentation Generator",
+  "description": "Generate comprehensive documentation for code",
+  "version": "1.0.0",
+  "author": "AI Agent Skills",
+  "tags": ["documentation", "docs", "jsdoc"]
+}
+EOF
+
+# 3. Create template
+cat > skills/doc-generator/generic.md << 'EOF'
+# Documentation Generator
+
+Generate comprehensive documentation for code including API docs, JSDoc, docstrings, etc.
+
+## Instructions
+
+1. Analyze the code structure
+2. Identify public APIs, functions, classes
+3. Generate documentation following the language's convention:
+   - JavaScript/TypeScript: JSDoc
+   - Python: Docstrings (Google/NumPy style)
+   - Java: JavaDoc
+   - C#: XML documentation
+4. Include parameters, return types, examples
+5. Add usage examples where helpful
+
+## Output Format
+
+Include:
+- Function/method description
+- Parameters with types
+- Return value with type
+- Examples (if complex)
+- Exceptions/errors thrown
+
+## Example
+
+```javascript
+/**
+ * Calculates the sum of two numbers
+ * @param {number} a - The first number
+ * @param {number} b - The second number
+ * @returns {number} The sum of a and b
+ * @example
+ * add(2, 3) // returns 5
+ */
+function add(a, b) {
+  return a + b;
+}
+```
+EOF
+```
+
+## How to Add a New Agent
+
+Adding support for a new AI agent is simple. Follow these steps:
+
+### 1. Open Agent Configuration
+
+Edit [lib/agents.js](lib/agents.js)
+
+### 2. Add Agent Object
+
+Add a new agent object to the `agents` array:
+
+```javascript
+{
+  id: 'my-agent',
+  name: 'My Agent',
+  description: 'Brief description of the agent',
+  getSkillsPath: () => {
+    const platform = os.platform();
+    if (platform === 'win32') {
+      return path.join(os.homedir(), 'AppData', 'Roaming', 'MyAgent', 'skills');
+    } else if (platform === 'darwin') {
+      return path.join(os.homedir(), 'Library', 'Application Support', 'MyAgent', 'skills');
+    } else {
+      return path.join(os.homedir(), '.config', 'my-agent', 'skills');
+    }
+  },
+  fileExtension: '.md',
+  template: 'my-agent'
+}
+```
+
+### 3. Agent Configuration Fields
+
+**Required Fields:**
+
+- `id` (string): Unique identifier (kebab-case)
+  - Used internally and in CLI selection
+  - Example: `'claude-code'`, `'my-agent'`
+
+- `name` (string): Display name
+  - Shown to users in the interactive menu
+  - Example: `'Claude Code'`, `'My Agent'`
+
+- `description` (string): Brief description
+  - Helps users identify the agent
+  - Example: `'Anthropic Claude Code CLI'`
+
+- `getSkillsPath` (function): Returns the default skills directory path
+  - Must handle Windows, macOS, and Linux
+  - Returns absolute path to where skills should be installed
+  - Platform-specific paths:
+    - **Windows**: `AppData/Roaming/[Agent]/skills`
+    - **macOS**: `Library/Application Support/[Agent]/skills`
+    - **Linux**: `.config/[agent]/skills`
+
+- `fileExtension` (string): File extension for skill files
+  - Usually `'.md'` for markdown
+  - Could be `'.txt'`, `'.json'`, etc. depending on agent
+
+- `template` (string): Template identifier
+  - Used to find agent-specific skill templates
+  - Should match template filename (e.g., `'my-agent'` → `my-agent.md`)
+  - Falls back to `'generic'` if template doesn't exist
+
+### 4. Finding the Skills Directory
+
+To find where your agent stores skills:
+
+1. **Check agent documentation** - Look for skills, plugins, or extensions directory
+2. **Check agent config** - Look in the agent's settings/configuration file
+3. **Common locations:**
+   - Windows: `%APPDATA%` or `%LOCALAPPDATA%`
+   - macOS: `~/Library/Application Support/`
+   - Linux: `~/.config/` or `~/.local/share/`
+
+### 5. Test Your Agent
+
+After adding the agent configuration:
+
+```bash
+npx ai-agent-skills
+# Select "List supported agents"
+# Verify your agent appears
+# Try installing a skill to your new agent
+```
+
+### Example: Adding "Windsurf" Agent
+
+```javascript
+{
+  id: 'windsurf',
+  name: 'Windsurf',
+  description: 'Windsurf AI Code Editor',
+  getSkillsPath: () => {
+    const platform = os.platform();
+    if (platform === 'win32') {
+      return path.join(os.homedir(), 'AppData', 'Roaming', 'Windsurf', 'skills');
+    } else if (platform === 'darwin') {
+      return path.join(os.homedir(), 'Library', 'Application Support', 'Windsurf', 'skills');
+    } else {
+      return path.join(os.homedir(), '.config', 'windsurf', 'skills');
+    }
+  },
+  fileExtension: '.md',
+  template: 'generic'  // Use generic template
+}
+```
+
+## Advanced: Agent-Specific Templates
+
+If your agent has unique requirements, create agent-specific templates:
+
+1. Set `template: 'my-agent'` in agent configuration
+2. Create `my-agent.md` files in skill directories
+3. The installer will use agent-specific templates when available
+4. Falls back to `generic.md` if agent-specific template doesn't exist
+
+**Example:** Claude Code might need specific formatting:
+
+```
+skills/code-review/
+├── skill.json
+├── claude-code.md    # Claude-specific format
+├── cline.md          # Cline-specific format
+└── generic.md        # Works for all others
+```
+
+## Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd ai-agent-skills
+
+# Install dependencies
+npm install
+
+# Test locally
+node bin/cli.js
+```
+
+### Publishing
+
+To publish to NPM:
+
+```bash
+# Login to NPM
+npm login
+
+# Publish
+npm publish
+```
+
+After publishing, users can run:
+```bash
+npx ai-agent-skills
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit:
+
+- New skills
+- Support for additional agents
+- Bug fixes
+- Documentation improvements
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions, please open an issue on the GitHub repository.