Add custom skill registries

Author: codeaholicguy

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **Custom Skill Registries** - Support `skills.registries` in global `~/.ai-devkit/.ai-devkit.json` for adding multiple registries that merge with defaults and override on conflicts.
+- **Global Registry Reader** - New global config reader for resolving custom registries in skill commands.
+
+### Changed
+- **Skill Registry Resolution** - Skill commands now merge default and custom registries, with offline cache fallback when a registry URL is not configured.
+
 ## [0.8.0] - 2026-01-26
 
 ### Added

docs/ai/implementation/feature-custom-skill-registries.md

@@ -26,7 +26,7 @@ description: Technical implementation notes, patterns, and code guidelines
 
 ### Core Features
 - Load default registry from remote `registry.json` (current behavior).
-- Load custom registries from global config using the same `registries` map format.
+- Load custom registries from global config using the same `skills.registries` map format.
 - Merge registries with custom entries overriding default on registry ID collision.
 - Use the merged registry map for all skill commands.
 - When remote registry fetch fails, fall back to cached registry data if available.
@@ -42,7 +42,7 @@ description: Technical implementation notes, patterns, and code guidelines
 - `SkillManager` calls into registry resolver for merged registry map.
 - Registry resolver reads:
   - Remote default registry JSON
-  - Global config `skillRegistries.registries`
+  - Global config `skills.registries`
 - Repository cloning remains in `cloneRepositoryToCache`.
 
 ## Error Handling

docs/ai/planning/feature-custom-skill-registries.md

@@ -17,19 +17,19 @@ description: Break down work into actionable tasks and estimate timeline
 **What specific work needs to be done?**
 
 ### Phase 1: Foundation
-- [ ] Task 1.1: Define global config schema for `skillRegistries`
-- [ ] Task 1.2: Add global config manager for `~/.ai-devkit/.ai-devkit.json`
-- [ ] Task 1.3: Update types to include optional `skillRegistries`
+- [x] Task 1.1: Define global config schema for `skills.registries` (Notes: aligned requirements/design docs)
+- [x] Task 1.2: Add global config manager for `~/.ai-devkit/.ai-devkit.json` (Notes: new `GlobalConfigManager` added)
+- [x] Task 1.3: Update types to include optional `skills.registries` (Notes: added `GlobalDevKitConfig` with `skills.registries`)
 
 ### Phase 2: Core Features
-- [ ] Task 2.1: Implement registry merge logic (custom overrides default)
-- [ ] Task 2.2: Update `SkillManager` to use merged registries for all commands
-- [ ] Task 2.3: Ensure offline behavior uses cached registries when remote fetch fails
+- [x] Task 2.1: Implement registry merge logic (custom overrides default) (Notes: merge in `SkillManager` with custom override)
+- [x] Task 2.2: Update `SkillManager` to use merged registries for all commands (Notes: addSkill now uses merged registries)
+- [x] Task 2.3: Ensure offline behavior uses cached registries when remote fetch fails (Notes: cached repo used if URL missing)
 
 ### Phase 3: Integration & Polish
-- [ ] Task 3.1: Add unit tests for registry merging and config parsing
-- [ ] Task 3.2: Add integration tests for skill commands with custom registries
-- [ ] Task 3.3: Update docs and finalize testing notes
+- [x] Task 3.1: Add unit tests for registry merging and config parsing (Notes: added GlobalConfig + SkillManager tests)
+- [x] Task 3.2: Add integration tests for skill commands with custom registries (Notes: added SkillManager test using real global config)
+- [x] Task 3.3: Update docs and finalize testing notes (Notes: updated requirements, implementation, testing docs)
 
 ## Dependencies
 **What needs to happen in what order?**

docs/ai/requirements/feature-custom-skill-registries.md

@@ -18,7 +18,7 @@ description: Clarify the problem space, gather requirements, and define success
 
 **What do we want to achieve?**
 
-- Allow multiple custom registries configured in a global `.ai-devkit.json`.
+- Allow multiple custom registries configured in a global `.ai-devkit.json` at `skills.registries`.
 - Use the same registry format as `skills/registry.json` (a `registries` map).
 - Merge default and custom registries for all skill commands.
 - Prioritize local (custom) registry entries over default when registry IDs conflict.
@@ -58,7 +58,7 @@ description: Clarify the problem space, gather requirements, and define success
 
 **What limitations do we need to work within?**
 
-- Custom registries use the same structure as `skills/registry.json`.
+- Custom registries use the same structure as `skills/registry.json` under `skills.registries`.
 - Registries are Git repositories that contain `skills/<skillName>/SKILL.md`.
 - User manages any authentication externally; CLI only clones locally.
 - Git must be installed for cloning.

docs/ai/testing/feature-custom-skill-registries.md

@@ -35,7 +35,7 @@ description: Define testing approach, test cases, and quality assurance
 ## Integration Tests
 **How do we test component interactions?**
 
-- [ ] Install a skill from a custom registry repo
+- [ ] Install a skill from a custom registry repo (via global config registries)
 - [ ] Install a skill when default registry is unreachable but cached
 - [ ] List skills after installing from custom registry
 - [ ] Remove a skill installed from custom registry

packages/cli/src/__tests__/lib/GlobalConfig.test.ts

@@ -0,0 +1,99 @@
+import * as fs from 'fs-extra';
+import * as os from 'os';
+import * as path from 'path';
+import { GlobalConfigManager } from '../../lib/GlobalConfig';
+
+jest.mock('fs-extra');
+jest.mock('os');
+jest.mock('path');
+
+describe('GlobalConfigManager', () => {
+  let configManager: GlobalConfigManager;
+  let mockFs: jest.Mocked<typeof fs>;
+  let mockOs: jest.Mocked<typeof os>;
+  let mockPath: jest.Mocked<typeof path>;
+
+  beforeEach(() => {
+    configManager = new GlobalConfigManager();
+    mockFs = fs as jest.Mocked<typeof fs>;
+    mockOs = os as jest.Mocked<typeof os>;
+    mockPath = path as jest.Mocked<typeof path>;
+
+    mockOs.homedir.mockReturnValue('/home/test');
+    mockPath.join.mockImplementation((...args) => args.join('/'));
+    jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('read', () => {
+    it('should return null when global config does not exist', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(false);
+
+      const result = await configManager.read();
+
+      expect(result).toBeNull();
+      expect(mockFs.readJson).not.toHaveBeenCalled();
+    });
+
+    it('should return parsed config when file exists', async () => {
+      const config = {
+        skills: {
+          registries: {
+            'my-org/skills': 'https://github.com/my-org/skills.git'
+          }
+        }
+      };
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue(config);
+
+      const result = await configManager.read();
+
+      expect(result).toEqual(config);
+      expect(mockFs.readJson).toHaveBeenCalledWith('/home/test/.ai-devkit/.ai-devkit.json');
+    });
+
+    it('should warn and return null when JSON is invalid', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockRejectedValue(new Error('Invalid JSON'));
+
+      const result = await configManager.read();
+
+      expect(result).toBeNull();
+      expect(console.warn).toHaveBeenCalled();
+    });
+  });
+
+  describe('getSkillRegistries', () => {
+    it('should return empty map when no config', async () => {
+      (mockFs.pathExists as any).mockResolvedValue(false);
+
+      const result = await configManager.getSkillRegistries();
+
+      expect(result).toEqual({});
+    });
+
+    it('should return only string registry entries', async () => {
+      const config = {
+        skills: {
+          registries: {
+            'my-org/skills': 'https://github.com/my-org/skills.git',
+            'bad/entry': 123
+          }
+        }
+      };
+
+      (mockFs.pathExists as any).mockResolvedValue(true);
+      (mockFs.readJson as any).mockResolvedValue(config);
+
+      const result = await configManager.getSkillRegistries();
+
+      expect(result).toEqual({
+        'my-org/skills': 'https://github.com/my-org/skills.git'
+      });
+    });
+  });
+});