ai-agent-config 2.1.0 → 2.2.0

package/.agent/skills/config-manager/SKILL.md

@@ -0,0 +1,184 @@
+# Config Manager Skill
+
+Manage ai-agent-config user configuration interactively.
+
+## When to Use This Skill
+
+Use this skill when the user needs to:
+- Add a new custom skill source from GitHub
+- Configure sync settings
+- Manage their skill sources (enable/disable/remove)
+- Export or import config files
+- Share config with team members
+- Understand how to configure ai-agent-config
+
+## Capabilities
+
+- **Source Management**: Add, remove, enable, disable custom skill sources
+- **Config Operations**: Get, set, validate, export, import config values
+- **Migration Support**: Help users migrate from v1 to v2
+- **Team Sharing**: Export configs for team collaboration
+
+## Command Reference
+
+### Source Management
+```bash
+# Add a custom source
+ai-agent source add <repo-url> --name <name> --branch <branch>
+
+# List all sources
+ai-agent source list
+
+# Enable/disable a source
+ai-agent source enable <name>
+ai-agent source disable <name>
+
+# Remove a custom source
+ai-agent source remove <name>
+
+# Get source info
+ai-agent source info <name>
+```
+
+### Config Management
+```bash
+# Get config value
+ai-agent config get <key>
+
+# Set config value
+ai-agent config set <key> <value>
+
+# Edit config in editor
+ai-agent config edit
+
+# Validate config
+ai-agent config validate
+
+# Export config
+ai-agent config export [output-file]
+
+# Import config
+ai-agent config import <file> [--merge]
+
+# Reset to defaults
+ai-agent config reset --yes
+```
+
+## Examples
+
+### Adding Company Skills
+
+**User**: "Add skills from my company's GitHub repo"
+
+**Assistant**: I'll help you add your company's skills repository. Use this command:
+
+```bash
+ai-agent source add https://github.com/yourcompany/ai-skills \
+  --name company-skills \
+  --branch main
+```
+
+After adding the source, you'll need to:
+1. Update skills: `ai-agent update --source company-skills`
+2. Edit config to specify which skills to use: `ai-agent config edit`
+3. Install to platforms: `ai-agent install`
+
+### Sharing Config with Team
+
+**User**: "How do I share my skill configuration with my team?"
+
+**Assistant**: You can export your config and share it with your team:
+
+```bash
+# Export your config
+ai-agent config export team-config.json
+
+# Team members can import it
+ai-agent config import team-config.json --merge
+```
+
+The `--merge` flag will combine your existing config with the imported one, keeping both official and custom sources.
+
+### Checking Current Config
+
+**User**: "What sources do I have configured?"
+
+**Assistant**: Run this command to see all your sources:
+
+```bash
+ai-agent source list
+```
+
+This will show both official sources (from the package) and your custom sources.
+
+## Config File Location
+
+- **User config**: `~/.ai-agent/config.json`
+- **Cache**: `~/.ai-agent-external-cache/`
+
+## Config Structure
+
+The v2.0 config file has this structure:
+
+```json
+{
+  "version": "2.0",
+  "sources": {
+    "official": [
+      {
+        "name": "vercel-labs",
+        "repo": "https://github.com/vercel-labs/agent-skills.git",
+        "branch": "main",
+        "enabled": true,
+        "skills": [...]
+      }
+    ],
+    "custom": [
+      {
+        "name": "my-skills",
+        "repo": "https://github.com/me/my-skills.git",
+        "branch": "main",
+        "enabled": true,
+        "skills": [...]
+      }
+    ]
+  },
+  "sync": {
+    "enabled": false,
+    "provider": null,
+    "config": {}
+  },
+  "preferences": {
+    "autoUpdate": true,
+    "updateInterval": "weekly"
+  }
+}
+```
+
+## Migration from v1.x
+
+If the user is on v1.x, help them migrate:
+
+```bash
+ai-agent init
+```
+
+This will automatically create the v2.0 config file with all official sources enabled.
+
+## Tips
+
+1. **Test before sharing**: Always validate your config before sharing: `ai-agent config validate`
+2. **Backup**: The config manager automatically creates backups when modifying config
+3. **Edit safely**: Use `ai-agent config edit` to open in your editor with syntax checking
+4. **Source names**: Use descriptive names for custom sources (e.g., "company-standards", "team-utils")
+
+## Troubleshooting
+
+**Problem**: "Source already exists" error
+**Solution**: Remove the old source first or use a different name
+
+**Problem**: Config validation errors
+**Solution**: Run `ai-agent config validate` to see specific errors, then fix manually or reset
+
+**Problem**: Can't find custom source
+**Solution**: Check the source is enabled: `ai-agent source info <name>`

package/.agent/skills/skill-updater/SKILL.md

@@ -0,0 +1,167 @@
+# Skill Updater
+
+Automatically update skills from all configured sources (official and custom).
+
+## When to Use This Skill
+
+Use this skill when the user wants to:
+- Update all skills from configured sources
+- Update a specific source
+- Update a specific skill
+- Sync latest changes from external repositories
+- Keep skills up to date with latest best practices
+
+## Capabilities
+
+- **Multi-Source Updates**: Updates from both official and custom sources
+- **Selective Updates**: Update specific source or skill
+- **Force Updates**: Overwrite local changes
+- **Progress Reporting**: Shows what was updated, copied, or skipped
+
+## Command Reference
+
+```bash
+# Update all skills from all sources
+ai-agent update
+
+# Update from specific source
+ai-agent update --source vercel-labs
+
+# Update specific skill
+ai-agent update --skill react-best-practices
+
+# Force overwrite existing skills
+ai-agent update --force
+
+# Combine options
+ai-agent update --source company-skills --force
+```
+
+## How It Works (v2.0)
+
+1. **Reads User Config**: Loads `~/.ai-agent/config.json`
+2. **Gets Enabled Sources**: Filters for enabled sources (official + custom)
+3. **Clones/Updates Repos**: For each source, clones to `~/.ai-agent-external-cache/`
+4. **Copies Skills**: Copies skills to `.agent/skills/` in the package directory
+5. **Reports Results**: Shows what was updated
+
+## Examples
+
+### Regular Update
+
+**User**: "Update my skills"
+
+**Assistant**: I'll update all your skills from configured sources:
+
+```bash
+ai-agent update
+```
+
+This will:
+- Pull latest from Vercel Labs, Everything Claude Code, etc.
+- Update your custom sources too
+- Copy new/updated skills to your system
+- Show what changed
+
+### Update After Adding Custom Source
+
+**User**: "I just added a custom source, how do I get the skills?"
+
+**Assistant**: After adding a source, update it:
+
+```bash
+# Update just your new source
+ai-agent update --source your-source-name
+
+# Then install to platforms
+ai-agent install
+```
+
+### Force Update
+
+**User**: "Some skills aren't updating"
+
+**Assistant**: Use `--force` to overwrite existing skills:
+
+```bash
+ai-agent update --force
+```
+
+⚠️ Warning: This will overwrite any local modifications you made to skills.
+
+## What's New in v2.0
+
+- ✅ **Custom Sources**: Updates from your custom sources, not just official ones
+- ✅ **User Config**: Reads from `~/.ai-agent/config.json` instead of hard-coded list
+- ✅ **Selective Sync**: Update specific sources or skills
+- ✅ **Better Reporting**: Shows which sources succeeded/failed
+
+## Update vs Install
+
+- **`ai-agent update`**: Downloads latest skills from sources to cache
+- **`ai-agent install`**: Installs cached skills to AI platforms (Claude, Antigravity, etc.)
+
+Typical workflow:
+```bash
+ai-agent update    # Get latest skills
+ai-agent install   # Install to platforms
+```
+
+## Configuration
+
+Skills are defined in your config file:
+
+```json
+{
+  "sources": {
+    "official": [
+      {
+        "name": "vercel-labs",
+        "enabled": true,
+        "skills": [
+          { "path": "skills/react-best-practices", "name": "react-best-practices" }
+        ]
+      }
+    ],
+    "custom": [
+      {
+        "name": "my-skills",
+        "enabled": true,
+        "skills": [
+          { "path": "skills/my-skill", "name": "my-skill" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Backward Compatibility
+
+The old command still works:
+```bash
+ai-agent sync-external
+```
+
+This is now an alias for `ai-agent update`.
+
+## Tips
+
+1. **Regular Updates**: Run `ai-agent update` weekly to get latest skills
+2. **Check Before Install**: After update, review changes before installing
+3. **Test Custom Sources**: When adding custom sources, test with `--source` flag first
+4. **Use Version Control**: If modifying skills, use git to track changes
+
+## Troubleshooting
+
+**Problem**: "Failed to load user config"
+**Solution**: Run `ai-agent init` to create config file
+
+**Problem**: Update fails for a source
+**Solution**: Check repo URL is correct: `ai-agent source info <name>`
+
+**Problem**: Skills not appearing
+**Solution**: Make sure source is enabled: `ai-agent source list`
+
+**Problem**: Git errors
+**Solution**: Check internet connection and git is installed

package/README.md

@@ -1,115 +1,197 @@
-# AI Agent Config
+# ai-agent-config
 
-> Universal Global Skills & Workflows for AI Coding Assistants
+> Universal Global Skills & Workflows for AI Coding Assistants - User-configurable skill sources
 
 [![npm version](https://badge.fury.io/js/ai-agent-config.svg)](https://www.npmjs.com/package/ai-agent-config)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Install a curated collection of AI agent skills from [github.com/dongitran/ai-agent-config](https://github.com/dongitran/ai-agent-config) to your global configuration.
+**One command to manage AI coding skills across Claude Code, Antigravity, Cursor, Windsurf, and more.**
 
-## How It Works
+## 🚀 What's New in v2.2
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  GitHub Repository                                              │
-│  github.com/dongitran/ai-agent-config                           │
-│  └── .agent/                                                    │
-│      ├── skills/         ◄── Skills are defined here            │
-│      │   ├── code-review/                                       │
-│      │   └── git-commit/                                        │
-│      └── workflows/                                             │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              │ ai-agent sync
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Local Cache                                                    │
-│  ~/.ai-agent-config-cache/                                      │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              │ ai-agent install
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  Platform Global Directories                                    │
-│  ├── ~/.claude/skills/           (Claude Code)                  │
-│  ├── ~/.gemini/antigravity/skills/ (Antigravity IDE)            │
-│  ├── ~/.cursor/skills/           (Cursor)                       │
-│  └── ~/.windsurf/skills/         (Windsurf)                     │
-└─────────────────────────────────────────────────────────────────┘
-```
+- ✅ **Minimal core** - Only 2 essential skills bundled (config-manager, skill-updater)
+- ✅ **User-configurable sources** - Add any skill repositories from GitHub
+- ✅ **Source management** - Enable, disable, add, remove sources via CLI
+- ✅ **Config management** - Export/import configs for team sharing
+- ✅ **Zero defaults** - No external sources by default, full user control
 
-## Installation
+## 📦 Quick Start
 
 ```bash
-# Install the CLI globally
+# Install globally
 npm install -g ai-agent-config
 
-# Sync skills from repository
-ai-agent sync
+# Initialize (creates config at ~/.ai-agent/config.json)
+ai-agent init
 
-# Install to your platforms
+# Install bundled skills to platforms
 ai-agent install
 ```
 
-## CLI Usage
+## 🎯 Bundled Skills (2)
+
+The package includes 2 core skills for managing the system:
+
+1. **config-manager** - Manage configuration and custom sources
+2. **skill-updater** - Update skills from GitHub repositories
+
+## 📚 Add More Skills
+
+To get more skills, add custom sources from GitHub:
 
 ```bash
-ai-agent help          # Show all commands
-ai-agent sync          # Sync from GitHub repository
-ai-agent install       # Install to all detected platforms
-ai-agent list          # List available skills
-ai-agent platforms     # Show detected platforms
-ai-agent uninstall     # Remove installed skills
+# Add Vercel Labs skills
+ai-agent source add https://github.com/vercel-labs/agent-skills.git \
+  --name vercel-labs \
+  --path skills
+
+# Add Everything Claude Code
+ai-agent source add https://github.com/affaan-m/everything-claude-code.git \
+  --name everything-claude-code \
+  --path skills
+
+# Update and install
+ai-agent update
+ai-agent install
 ```
 
-### Options
+## 🛠️ CLI Commands
 
+### Source Management
 ```bash
-ai-agent install --platform claude   # Install to specific platform
-ai-agent install --skill code-review # Install specific skill
-ai-agent install --force             # Overwrite existing files
+ai-agent source add <repo-url> [options]    # Add custom source
+ai-agent source remove <name>               # Remove source
+ai-agent source list                        # List all sources
+ai-agent source enable <name>               # Enable source
+ai-agent source disable <name>              # Disable source
+ai-agent source info <name>                 # View source details
 ```
 
-## Supported Platforms
+### Config Management
+```bash
+ai-agent config get <key>                   # Get config value
+ai-agent config set <key> <value>           # Set config value
+ai-agent config edit                        # Edit in $EDITOR
+ai-agent config validate                    # Validate config
+ai-agent config export [file]               # Export config
+ai-agent config import <file> [--merge]     # Import config
+ai-agent config reset --yes                 # Reset to defaults
+```
 
-| Platform | Global Skills Path |
-|----------|-------------------|
-| Claude Code | `~/.claude/skills/` |
-| Antigravity IDE | `~/.gemini/antigravity/skills/` |
-| Cursor | `~/.cursor/skills/` |
-| Windsurf | `~/.windsurf/skills/` |
-| Codex CLI | `~/.codex/skills/` |
+### Installation & Updates
+```bash
+ai-agent init                               # Initialize/migrate to v2.0
+ai-agent update [--source name]             # Update skills from sources
+ai-agent install [--platform name]          # Install to platforms
+ai-agent list                               # List installed skills
+ai-agent platforms                          # Show detected platforms
+ai-agent uninstall                          # Remove skills
+```
 
-## Available Skills
+## 🎨 Use Cases
 
-Skills are defined in the repository's `.agent/skills/` directory:
+### For Companies
+```bash
+# Add your company's private skills repo
+ai-agent source add https://github.com/acme-corp/coding-standards \
+  --name acme-standards
 
-- **code-review** - Thorough code review with security, performance checks
-- **git-commit** - Conventional commit message formatting
-- *More coming soon...*
+# Share config file with team
+ai-agent config export acme-config.json
 
-## Configuration
+# Team members import
+ai-agent config import acme-config.json --merge
+```
 
-Optional config at `~/.ai-agent-config.json`:
+### For Individual Developers
+```bash
+# Add skills from multiple sources
+ai-agent source add https://github.com/vercel-labs/agent-skills.git --name vercel
+ai-agent source add https://github.com/yourname/my-skills --name personal
+
+# Update and install
+ai-agent update
+ai-agent install
+```
+
+## 📍 File Locations
+
+```
+~/.ai-agent/
+├── config.json                    # User configuration
+└── .ai-agent-external-cache/      # Downloaded skill repositories
+
+AI Platform Skills:
+~/.claude/skills/                  # Claude Code
+~/.gemini/antigravity/skills/      # Antigravity IDE
+~/.cursor/skills/                  # Cursor
+~/.windsurf/skills/                # Windsurf
+```
+
+## 🔧 Configuration File
+
+User config at `~/.ai-agent/config.json`:
 
 ```json
 {
-  "platforms": ["claude", "antigravity"],
-  "skills": {
-    "include": ["*"],
-    "exclude": []
+  "version": "2.0",
+  "sources": {
+    "official": [],
+    "custom": [
+      {
+        "name": "my-skills",
+        "repo": "https://github.com/me/my-skills.git",
+        "branch": "main",
+        "path": "skills",
+        "enabled": true
+      }
+    ]
+  },
+  "preferences": {
+    "autoUpdate": true,
+    "updateInterval": "weekly"
   }
 }
 ```
 
-## Contributing
+## 🤝 Contributing
+
+We welcome contributions! Here's how:
+
+1. **Share your skills**: Create skills repo and share with community
+2. **Report issues**: [GitHub Issues](https://github.com/dongitran/ai-agent-config/issues)
+3. **Submit PRs**: Improve the core tool
+
+## 🌟 Why ai-agent-config?
+
+- ✅ **Minimal & focused** - Only 2 core skills bundled, add what you need
+- ✅ **Full control** - No default external sources, you decide what to install
+- ✅ **User-configurable** - Add unlimited custom skill sources
+- ✅ **Team-friendly** - Export/import configs for collaboration
+- ✅ **Zero dependencies** - Lightweight, fast, secure
+- ✅ **Open & extensible** - Use any GitHub repo as skill source
+
+## 📊 Supported Platforms
+
+| Platform | Status | Skills Directory |
+|----------|--------|------------------|
+| Claude Code | ✅ Supported | `~/.claude/skills/` |
+| Antigravity IDE | ✅ Supported | `~/.gemini/antigravity/skills/` |
+| Cursor | ✅ Supported | `~/.cursor/skills/` |
+| Windsurf | ✅ Supported | `~/.windsurf/skills/` |
+| Codex CLI | ✅ Supported | `~/.codex/skills/` |
+
+## 📄 License
+
+MIT © [Dong Tran](https://github.com/dongitran)
 
-Add your skills to the repository:
+## 🔗 Links
 
-1. Fork [github.com/dongitran/ai-agent-config](https://github.com/dongitran/ai-agent-config)
-2. Create skill in `.agent/skills/your-skill/SKILL.md`
-3. Submit a pull request
+- **NPM**: https://www.npmjs.com/package/ai-agent-config
+- **GitHub**: https://github.com/dongitran/ai-agent-config
+- **Issues**: https://github.com/dongitran/ai-agent-config/issues
+- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 
-## License
+---
 
-MIT
+**Keywords**: AI coding assistant, Claude Code, Antigravity, Cursor, Windsurf, AI skills, code automation, developer tools, coding standards, best practices, AI agent config, skill management, team collaboration, custom skills, GitHub integration

package/config/official-sources.json

@@ -1,103 +1,5 @@
 {
   "$schema": "https://ai-agent-config.dev/schema/v2.json",
   "version": "2.0",
-  "sources": [
-    {
-      "name": "vercel-labs",
-      "repo": "https://github.com/vercel-labs/agent-skills.git",
-      "branch": "main",
-      "skills": [
-        {
-          "path": "skills/react-best-practices",
-          "name": "react-best-practices"
-        },
-        {
-          "path": "skills/web-design-guidelines",
-          "name": "web-design-guidelines"
-        }
-      ],
-      "license": "MIT",
-      "attribution": "Skills from Vercel Labs (https://github.com/vercel-labs/agent-skills)"
-    },
-    {
-      "name": "everything-claude-code",
-      "repo": "https://github.com/affaan-m/everything-claude-code.git",
-      "branch": "main",
-      "skills": [
-        {
-          "path": "skills/backend-patterns",
-          "name": "backend-patterns"
-        },
-        {
-          "path": "skills/coding-standards",
-          "name": "coding-standards"
-        },
-        {
-          "path": "skills/continuous-learning",
-          "name": "continuous-learning"
-        },
-        {
-          "path": "skills/eval-harness",
-          "name": "eval-harness"
-        },
-        {
-          "path": "skills/frontend-patterns",
-          "name": "frontend-patterns"
-        },
-        {
-          "path": "skills/postgres-patterns",
-          "name": "postgres-patterns"
-        },
-        {
-          "path": "skills/project-guidelines-example",
-          "name": "project-guidelines-example"
-        },
-        {
-          "path": "skills/security-review",
-          "name": "security-review"
-        },
-        {
-          "path": "skills/strategic-compact",
-          "name": "strategic-compact"
-        },
-        {
-          "path": "skills/tdd-workflow",
-          "name": "tdd-workflow"
-        },
-        {
-          "path": "skills/verification-loop",
-          "name": "verification-loop"
-        }
-      ],
-      "license": "MIT",
-      "attribution": "Skills from Everything Claude Code by Affaan Mustafa (https://github.com/affaan-m/everything-claude-code)"
-    },
-    {
-      "name": "playwright-skill",
-      "repo": "https://github.com/lackeyjb/playwright-skill.git",
-      "branch": "main",
-      "skills": [
-        {
-          "path": "skills/playwright-skill",
-          "name": "playwright"
-        }
-      ],
-      "license": "MIT",
-      "attribution": "Playwright skill from lackeyjb (https://github.com/lackeyjb/playwright-skill)"
-    },
-    {
-      "name": "agent-nestjs-skills",
-      "repo": "https://github.com/Kadajett/agent-nestjs-skills.git",
-      "branch": "main",
-      "skills": [
-        {
-          "path": ".",
-          "name": "nestjs-best-practices",
-          "excludePaths": [".git", ".github", "README.md", "scripts", "website"]
-        }
-      ],
-      "license": "MIT",
-      "attribution": "NestJS Best Practices from Kadajett (https://github.com/Kadajett/agent-nestjs-skills)"
-    }
-  ]
+  "sources": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agent-config",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Universal Global Skills & Workflows for AI Coding Assistants (Claude Code, Antigravity, Cursor) - v2.0: User-configurable skill sources",
   "main": "index.js",
   "bin": {
@@ -42,6 +42,7 @@
     "bin/",
     "scripts/",
     "config/",
+    ".agent/",
     "index.js",
     "README.md"
   ]

package/scripts/postinstall.js

@@ -23,13 +23,19 @@ function main() {
     console.log("");
   }
 
+  console.log("📦 Bundled Skills:\n");
+  console.log("   • config-manager     - Manage configuration and sources");
+  console.log("   • skill-updater      - Update skills from repositories\n");
+
   console.log("📖 Quick Start:\n");
-  console.log("   1. Sync skills from repository:");
-  console.log("      $ ai-agent sync\n");
-  console.log("   2. Install to your platforms:");
+  console.log("   1. Initialize config:");
+  console.log("      $ ai-agent init\n");
+  console.log("   2. Install bundled skills to platforms:");
   console.log("      $ ai-agent install\n");
-  console.log("   3. View available skills:");
-  console.log("      $ ai-agent list\n");
+  console.log("   3. (Optional) Add more skills from GitHub:");
+  console.log("      $ ai-agent source add <repo-url>\n");
+  console.log("   4. Update & install additional skills:");
+  console.log("      $ ai-agent update && ai-agent install\n");
   console.log("📦 Repository: https://github.com/dongitran/ai-agent-config\n");
 }