Add requirement for skill custom registry

Author: codeaholicguy

.ai-devkit.json

@@ -12,5 +12,5 @@
     "testing"
   ],
   "createdAt": "2025-12-28T13:35:45.251Z",
-  "updatedAt": "2026-01-25T14:05:14.517Z"
+  "updatedAt": "2026-01-26T20:02:55.191Z"
 }

AGENTS.md

@@ -28,6 +28,56 @@ This project uses ai-devkit for structured AI-assisted development. Phase docume
 - For new features, start with requirements clarification
 - Update phase docs when significant changes or decisions are made
 
+## Skills (Extend Your Capabilities)
+Skills are packaged capabilities that teach you new competencies, patterns, and best practices. Check for installed skills in the project's skill directory and use them to enhance your work.
+
+### Using Installed Skills
+1. **Check for skills**: Look for `SKILL.md` files in the project's skill directory
+2. **Read skill instructions**: Each skill contains detailed guidance on when and how to use it
+3. **Apply skill knowledge**: Follow the patterns, commands, and best practices defined in the skill
+
+### Key Installed Skills
+- **memory**: Use AI DevKit's memory service via CLI commands when MCP is unavailable. Read the skill for detailed `memory store` and `memory search` command usage.
+
+### When to Reference Skills
+- Before implementing features that match a skill's domain
+- When MCP tools are unavailable but skill provides CLI alternatives
+- To follow established patterns and conventions defined in skills
+
+## Knowledge Memory (Always Use When Helpful)
+The AI assistant should proactively use knowledge memory throughout all interactions.
+
+> **Tip**: If MCP is unavailable, use the **memory skill** for detailed CLI command reference.
+
+### When to Search Memory
+- Before starting any task, search for relevant project conventions, patterns, or decisions
+- When you need clarification on how something was done before
+- To check for existing solutions to similar problems
+- To understand project-specific terminology or standards
+
+**How to search**:
+- Use `memory.searchKnowledge` MCP tool with relevant keywords, tags, and scope
+- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command (see memory skill for details)
+- Example: Search for "authentication patterns" when implementing auth features
+
+### When to Store Memory
+- After making important architectural or design decisions
+- When discovering useful patterns or solutions worth reusing
+- If the user explicitly asks to "remember this" or save guidance
+- When you establish new conventions or standards for the project
+
+**How to store**:
+- Use `memory.storeKnowledge` MCP tool
+- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command (see memory skill for details)
+- Include clear title, detailed content, relevant tags, and appropriate scope
+- Make knowledge specific and actionable, not generic advice
+
+### Memory Best Practices
+- **Be Proactive**: Search memory before asking the user repetitive questions
+- **Be Specific**: Store knowledge that's actionable and reusable
+- **Use Tags**: Tag knowledge appropriately for easy discovery (e.g., "api", "testing", "architecture")
+- **Scope Appropriately**: Use `global` for general patterns, `project:<name>` for project-specific knowledge
+
 ## Testing & Quality
 - Write tests alongside implementation
 - Follow the testing strategy defined in `docs/ai/testing/`
@@ -47,5 +97,5 @@ When working on this project, you can run commands to:
 - Review architectural decisions (`review-design`)
 - Plan and execute tasks (`execute-plan`)
 - Verify implementation against design (`check-implementation`)
-- Suggest missing tests (`suggest-tests`)
-- Perform structured code reviews (`code-review`)
+- Writing tests (`writing-test`)
+- Perform structured code reviews (`code-review`)

CLAUDE.md

@@ -28,6 +28,56 @@ This project uses ai-devkit for structured AI-assisted development. Phase docume
 - For new features, start with requirements clarification
 - Update phase docs when significant changes or decisions are made
 
+## Skills (Extend Your Capabilities)
+Skills are packaged capabilities that teach you new competencies, patterns, and best practices. Check for installed skills in the project's skill directory and use them to enhance your work.
+
+### Using Installed Skills
+1. **Check for skills**: Look for `SKILL.md` files in the project's skill directory
+2. **Read skill instructions**: Each skill contains detailed guidance on when and how to use it
+3. **Apply skill knowledge**: Follow the patterns, commands, and best practices defined in the skill
+
+### Key Installed Skills
+- **memory**: Use AI DevKit's memory service via CLI commands when MCP is unavailable. Read the skill for detailed `memory store` and `memory search` command usage.
+
+### When to Reference Skills
+- Before implementing features that match a skill's domain
+- When MCP tools are unavailable but skill provides CLI alternatives
+- To follow established patterns and conventions defined in skills
+
+## Knowledge Memory (Always Use When Helpful)
+The AI assistant should proactively use knowledge memory throughout all interactions.
+
+> **Tip**: If MCP is unavailable, use the **memory skill** for detailed CLI command reference.
+
+### When to Search Memory
+- Before starting any task, search for relevant project conventions, patterns, or decisions
+- When you need clarification on how something was done before
+- To check for existing solutions to similar problems
+- To understand project-specific terminology or standards
+
+**How to search**:
+- Use `memory.searchKnowledge` MCP tool with relevant keywords, tags, and scope
+- If MCP tools are unavailable, use `npx ai-devkit memory search` CLI command (see memory skill for details)
+- Example: Search for "authentication patterns" when implementing auth features
+
+### When to Store Memory
+- After making important architectural or design decisions
+- When discovering useful patterns or solutions worth reusing
+- If the user explicitly asks to "remember this" or save guidance
+- When you establish new conventions or standards for the project
+
+**How to store**:
+- Use `memory.storeKnowledge` MCP tool
+- If MCP tools are unavailable, use `npx ai-devkit memory store` CLI command (see memory skill for details)
+- Include clear title, detailed content, relevant tags, and appropriate scope
+- Make knowledge specific and actionable, not generic advice
+
+### Memory Best Practices
+- **Be Proactive**: Search memory before asking the user repetitive questions
+- **Be Specific**: Store knowledge that's actionable and reusable
+- **Use Tags**: Tag knowledge appropriately for easy discovery (e.g., "api", "testing", "architecture")
+- **Scope Appropriately**: Use `global` for general patterns, `project:<name>` for project-specific knowledge
+
 ## Testing & Quality
 - Write tests alongside implementation
 - Follow the testing strategy defined in `docs/ai/testing/`
@@ -47,5 +97,5 @@ When working on this project, you can run commands to:
 - Review architectural decisions (`review-design`)
 - Plan and execute tasks (`execute-plan`)
 - Verify implementation against design (`check-implementation`)
-- Suggest missing tests (`suggest-tests`)
-- Perform structured code reviews (`code-review`)
+- Writing tests (`writing-test`)
+- Perform structured code reviews (`code-review`)

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

@@ -0,0 +1,92 @@
+---
+phase: design
+title: System Design & Architecture
+description: Define the technical architecture, components, and data models
+---
+
+# System Design & Architecture
+
+## Architecture Overview
+
+**What is the high-level system structure?**
+
+- Add a registry resolution layer that merges default and custom registries before skill operations.
+- Default registry remains fetched from the current remote registry JSON.
+- Custom registries are read from a global `.ai-devkit.json`.
+- Skill commands use the merged registry map with local overrides.
+
+```mermaid
+graph TD
+  CLI[ai-devkit skill commands] --> SkillManager
+  SkillManager --> RegistryResolver
+  RegistryResolver --> DefaultRegistry[Remote registry.json]
+  RegistryResolver --> GlobalConfig[~/.ai-devkit/.ai-devkit.json]
+  RegistryResolver --> MergedRegistry[merged registries map]
+  SkillManager --> Cache[~/.ai-devkit/skills]
+```
+
+## Data Models
+
+**What data do we need to manage?**
+
+- Global config (new or extended):
+  - `skills.registries` (map of `registryId -> gitUrl`)
+- Registry JSON (existing):
+  - `registries` map of registry IDs to Git URLs
+
+Example global config snippet:
+
+```json
+{
+  "skills": {
+    "registries": {
+      "my-org/skills": "git@github.com:my-org/skills.git",
+      "me/personal-skills": "https://github.com/me/personal-skills.git"
+    }
+  }
+}
+```
+
+## API Design
+
+**How do components communicate?**
+
+- CLI commands (`skill add`, `skill list`, `skill remove`, `skill update`, `skill search`) call `SkillManager`.
+- `SkillManager` uses a new helper (e.g., `RegistryResolver`) to:
+  - Load default registry (remote JSON).
+  - Load custom registries from global config.
+  - Merge with custom overrides on conflict.
+- No external API changes; internal interface remains synchronous with current workflow.
+
+## Component Breakdown
+
+**What are the major building blocks?**
+
+- `SkillManager`: update to use merged registries for all commands.
+- `GlobalConfigManager` (new): read/write `~/.ai-devkit/.ai-devkit.json`.
+- `RegistryResolver` (new or within SkillManager): merge registry sources.
+- Cache handler (existing): reuse `~/.ai-devkit/skills`.
+
+## Design Decisions
+
+**Why did we choose this approach?**
+
+- Use existing registry format to avoid new parsing logic.
+- Keep CLI UX unchanged by merging sources before lookup.
+- Local override provides predictable behavior for conflicts.
+- Cache reuse enables offline workflows without new storage systems.
+
+Alternatives considered:
+
+- Separate registry list files per project (rejected: requirement is global).
+- Display registry source in list output (rejected: keep seamless UX).
+
+## Non-Functional Requirements
+
+**How should the system perform?**
+
+- Performance: avoid repeated registry downloads by caching and only fetching when needed.
+- Scalability: support many registries by merging maps and cloning on demand.
+- Security: rely on git and local credentials; no credential handling in CLI.
+- Reliability: fall back to cache when remote registry is unavailable.
+

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

@@ -0,0 +1,65 @@
+---
+phase: implementation
+title: Implementation Guide
+description: Technical implementation notes, patterns, and code guidelines
+---
+
+# Implementation Guide
+
+## Development Setup
+**How do we get started?**
+
+- Ensure git is installed and available in PATH.
+- Identify the global config location (assumed: `~/.ai-devkit/.ai-devkit.json`).
+- Prepare a sample custom registry repo for local testing.
+
+## Code Structure
+**How is the code organized?**
+
+- `packages/cli/src/lib/SkillManager.ts`: main skill command logic
+- `packages/cli/src/lib/Config.ts`: project config manager (existing)
+- New: `GlobalConfigManager` for global `.ai-devkit.json`
+- New or inline: registry merge helper (e.g., `RegistryResolver`)
+
+## Implementation Notes
+**Key technical details to remember:**
+
+### Core Features
+- Load default registry from remote `registry.json` (current behavior).
+- Load custom registries from global config using the same `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.
+
+### Patterns & Best Practices
+- Keep registry merging logic centralized to avoid command drift.
+- Use explicit, user-facing errors when registry IDs or skills are not found.
+- Preserve existing cache behavior to maintain offline support.
+
+## Integration Points
+**How do pieces connect?**
+
+- `SkillManager` calls into registry resolver for merged registry map.
+- Registry resolver reads:
+  - Remote default registry JSON
+  - Global config `skillRegistries.registries`
+- Repository cloning remains in `cloneRepositoryToCache`.
+
+## Error Handling
+**How do we handle failures?**
+
+- If registry fetch fails but cache exists, continue with cache.
+- If a registry ID is missing in the merged map, return available registry IDs.
+- If skill path or `SKILL.md` missing, show a clear error.
+
+## Performance Considerations
+**How do we keep it fast?**
+
+- Avoid re-cloning registries when cache exists.
+- Keep registry JSON fetch to a single request per command invocation.
+
+## Security Notes
+**What security measures are in place?**
+
+- No credential handling in CLI; rely on user-managed git credentials.
+- Do not execute any scripts from cloned repositories.

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

@@ -0,0 +1,60 @@
+---
+phase: planning
+title: Project Planning & Task Breakdown
+description: Break down work into actionable tasks and estimate timeline
+---
+
+# Project Planning & Task Breakdown
+
+## Milestones
+**What are the major checkpoints?**
+
+- [ ] Milestone 1: Global registry config support and merge logic
+- [ ] Milestone 2: Skill commands updated and tested
+- [ ] Milestone 3: Documentation and testing finalized
+
+## Task Breakdown
+**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`
+
+### 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
+
+### 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
+
+## Dependencies
+**What needs to happen in what order?**
+
+- Global config schema and manager must be in place before skill command updates.
+- Merge logic should be implemented before modifying command behavior.
+- Tests depend on updated `SkillManager` behavior and new config handling.
+
+## Timeline & Estimates
+**When will things be done?**
+
+- Phase 1: 0.5-1 day
+- Phase 2: 1-2 days
+- Phase 3: 0.5-1 day
+
+## Risks & Mitigation
+**What could go wrong?**
+
+- Registry conflicts cause unexpected behavior → enforce clear override rules.
+- Remote registry fetch failure breaks commands → fallback to cache and log.
+- Config path ambiguity → document and test explicit path.
+
+## Resources Needed
+**What do we need to succeed?**
+
+- Access to a sample custom registry repo for testing
+- Git installed and available in CI/dev environments
+- Updated documentation and test templates