ai-agent-config 2.1.1 → 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

@@ -7,13 +7,13 @@
 
 **One command to manage AI coding skills across Claude Code, Antigravity, Cursor, Windsurf, and more.**
 
-## 🚀 What's New in v2.1
+## 🚀 What's New in v2.2
 
-- ✅ **User-configurable sources** - Add custom skill repositories from GitHub
+- ✅ **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
-- ✅ **Auto-migration** - Seamless upgrade from v2.0
-- ✅ **Backward compatible** - All v2.0 commands still work
+- ✅ **Zero defaults** - No external sources by default, full user control
 
 ## 📦 Quick Start
 
@@ -24,87 +24,31 @@ npm install -g ai-agent-config
 # Initialize (creates config at ~/.ai-agent/config.json)
 ai-agent init
 
-# Update skills from all sources
-ai-agent update
-
-# Install to your AI platforms
-ai-agent install
-```
-
-## 🎯 Key Features
-
-### Add Custom Skills from Any GitHub Repo
-
-```bash
-# Add your company's skills
-ai-agent source add https://github.com/mycompany/ai-skills \
-  --name company-skills \
-  --branch main \
-  --path skills \
-  --exclude .git,README.md
-
-# Update and install
-ai-agent update
+# Install bundled skills to platforms
 ai-agent install
 ```
 
-### Manage Skill Sources
-
-```bash
-# List all sources (official + custom)
-ai-agent source list
+## 🎯 Bundled Skills (2)
 
-# Enable/disable sources
-ai-agent source disable playwright-skill
-ai-agent source enable vercel-labs
+The package includes 2 core skills for managing the system:
 
-# Remove custom source
-ai-agent source remove old-source
+1. **config-manager** - Manage configuration and custom sources
+2. **skill-updater** - Update skills from GitHub repositories
 
-# View source details
-ai-agent source info company-skills
-```
+## 📚 Add More Skills
 
-### Share Config with Your Team
+To get more skills, add custom sources from GitHub:
 
 ```bash
-# Export your config
-ai-agent config export team-config.json
-
-# Team members import
-ai-agent config import team-config.json --merge
-```
-
-## 📚 Available Skills
-
-### Official Sources (4 curated repositories)
-
-After running `ai-agent update`, you'll have access to 15+ skills from:
-
-1. **Vercel Labs** - Frontend best practices
-   - `react-best-practices`, `web-design-guidelines`
-
-2. **Everything Claude Code** - Full-stack development
-   - `backend-patterns`, `coding-standards`, `continuous-learning`
-   - `eval-harness`, `frontend-patterns`, `postgres-patterns`
-   - `project-guidelines-example`, `security-review`
-   - `strategic-compact`, `tdd-workflow`, `verification-loop`
-
-3. **Playwright Skill** - Browser automation
-   - `playwright`
-
-4. **NestJS Skills** - Backend framework
-   - `nestjs-best-practices`
+# Add Vercel Labs skills
+ai-agent source add https://github.com/vercel-labs/agent-skills.git \
+  --name vercel-labs \
+  --path skills
 
-### Add Your Own Skills
-
-```bash
-# Add personal skills
-ai-agent source add https://github.com/yourname/my-skills
-
-# Add company skills
-ai-agent source add https://github.com/company/team-skills \
-  --name company-standards
+# 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
@@ -148,40 +92,26 @@ ai-agent uninstall                          # Remove skills
 
 ### For Companies
 ```bash
-# 1. Create private skills repo
-# 2. Add to all team members
+# Add your company's private skills repo
 ai-agent source add https://github.com/acme-corp/coding-standards \
   --name acme-standards
 
-# 3. Share config file
+# Share config file with team
 ai-agent config export acme-config.json
-# Send to team via Slack/Email
 
-# 4. Team members import
+# Team members import
 ai-agent config import acme-config.json --merge
 ```
 
 ### For Individual Developers
 ```bash
 # Add skills from multiple sources
-ai-agent source add https://github.com/username/my-skills
-ai-agent source add https://github.com/another/awesome-skills
-
-# Disable skills you don't use
-ai-agent source disable playwright-skill
+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
 
-# Keep only what you need
+# Update and install
 ai-agent update
-```
-
-### For Open Source Projects
-```bash
-# Create project-specific skills
-# Share via GitHub repo
-# Contributors use the same standards
-
-ai-agent source add https://github.com/project/ai-skills \
-  --name project-standards
+ai-agent install
 ```
 
 ## 📍 File Locations
@@ -206,22 +136,13 @@ User config at `~/.ai-agent/config.json`:
 {
   "version": "2.0",
   "sources": {
-    "official": [
-      {
-        "name": "vercel-labs",
-        "repo": "https://github.com/vercel-labs/agent-skills.git",
-        "branch": "main",
-        "enabled": true,
-        "skills": [...]
-      }
-    ],
+    "official": [],
     "custom": [
       {
         "name": "my-skills",
         "repo": "https://github.com/me/my-skills.git",
         "branch": "main",
         "path": "skills",
-        "excludePaths": [".git", "README.md"],
         "enabled": true
       }
     ]
@@ -237,32 +158,16 @@ User config at `~/.ai-agent/config.json`:
 
 We welcome contributions! Here's how:
 
-1. **Add skills to official sources**: Submit PR to add new curated sources
+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. **Share your skills**: Create skills repo and share with community
-
-## 📖 Migration from v1.x
-
-v2.0 automatically migrates your setup:
-
-```bash
-# Install v2.0
-npm install -g ai-agent-config@latest
-
-# Run init (auto-detects v1 and migrates)
-ai-agent init
-
-# ✅ Done! All your skills are preserved
-```
-
-**No breaking changes** - All v1 commands work in v2.
+3. **Submit PRs**: Improve the core tool
 
 ## 🌟 Why ai-agent-config?
 
-- ✅ **One source of truth** for AI coding skills across all platforms
+- ✅ **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
-- ✅ **Auto-sync** - Weekly updates from official sources
 - ✅ **Zero dependencies** - Lightweight, fast, secure
 - ✅ **Open & extensible** - Use any GitHub repo as skill source
 
@@ -274,7 +179,7 @@ ai-agent init
 | Antigravity IDE | ✅ Supported | `~/.gemini/antigravity/skills/` |
 | Cursor | ✅ Supported | `~/.cursor/skills/` |
 | Windsurf | ✅ Supported | `~/.windsurf/skills/` |
-| Copilot (GitHub) | 🔄 Coming soon | - |
+| Codex CLI | ✅ Supported | `~/.codex/skills/` |
 
 ## 📄 License
 

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.1",
+  "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");
 }