How to Add Support for Custom or Unsupported AI Agents in the Agent-Skills System

To add support for a custom or unsupported AI agent, extend the AGENT_TYPES array in libs/core/src/lib/types.ts and define a new entry in the agentDefinitions map located in libs/core/src/lib/services/agents.service.ts that implements filesystem or VS Code extension detection logic.

The tech-leads-club/agent-skills monorepo treats every AI coding agent as a typed configuration spanning compile-time types, runtime maps, and CLI validation. Adding support for custom or unsupported AI agents requires updating three specific integration points to maintain type safety across the core library and CLI packages.

The Three-Layer Architecture for Agent Support

The system maintains agent definitions across three synchronized layers to ensure end-to-end type safety.

Compile-Time Type Safety with AGENT_TYPES

The AGENT_TYPES constant in libs/core/src/lib/types.ts (lines 54-73) declares the exhaustive list of supported agent identifiers. This array generates the AgentType union type used throughout the codebase for function parameters, return types, and lockfile schemas. Adding your custom agent here ensures TypeScript recognizes the identifier across all consuming modules.

Runtime Configuration via agentDefinitions

The agentDefinitions object in libs/core/src/lib/services/agents.service.ts (lines 22-86) maps each AgentType to an AgentDefinition containing the display name, description, skill directory paths, and installation detection logic. The getAgentConfig function (lines 20-32) consumes these definitions to resolve destination paths during skill installation.

Automatic CLI Validation

The CLI commands in packages/cli/src/cli/install.ts and packages/cli/src/cli/remove.ts (lines 2-9) validate the --agent argument against AGENT_TYPES. When you extend the types array, the CLI automatically accepts your custom agent identifier without additional validation code.

Step-by-Step Implementation Guide

Follow these steps to integrate a new AI agent into the ecosystem.

Step 1: Register the Agent Type Identifier

Add your custom agent identifier to the AGENT_TYPES array in the core types file. This generates a new union member that the lockfile service and CLI commands will recognize immediately.

// libs/core/src/lib/types.ts
export const AGENT_TYPES = [
  // ... existing entries (cline, roo, etc.) ...
  'myagent',
] as const

Step 2: Create the Agent Definition

Insert a new entry into the agentDefinitions record in the agents service file. The definition requires five specific fields to enable proper skill routing and detection.

// libs/core/src/lib/services/agents.service.ts
const agentDefinitions: Record<AgentType, AgentDefinition> = {
  // ... existing agents ...

  myagent: {
    displayName: 'MyAgent',
    description: 'A custom AI coding assistant for specialized workflows',
    // Relative path from project root where local skills are stored
    skillsDir: '.myagent/skills',
    // Function returning global install directory (usually under $HOME)
    globalSkillsDir: (home) => join(home, '.myagent/skills'),
    // Detection logic - returns true if agent is installed
    detectInstalled: ({ home, projectRoot, ports }) =>
      ports.fs.existsSync(join(home, '.myagent')) ||
      ports.fs.existsSync(join(projectRoot, '.myagent')),
  },
}

The detectInstalled function receives a ports object containing filesystem access (ports.fs), the user's home directory, and the project root. Return true when your agent's configuration directory or binary exists on the system.

Step 3: Implement VS Code Extension Detection (Optional)

If your agent distributes as a VS Code extension, reuse the isExtensionInstalled helper function from the same file to check for the extension publisher and name.

// Inside agentDefinitions.myagent:
detectInstalled: ({ home, projectRoot, ports }) =>
  isExtensionInstalled({ home, ports }, 'mycorp', 'myagent') ||
  ports.fs.existsSync(join(home, '.myagent')),

This pattern matches how the system detects Cline and Roo agents that ship as VS Code marketplace extensions.

Step 4: Test the Integration

Add a unit test in libs/core/src/lib/services/__tests__/agents.service.spec.ts to verify the detection logic. Mock the filesystem ports and assert that detectInstalledAgents returns your new type when expected.

// libs/core/src/lib/services/__tests__/agents.service.spec.ts
import { detectInstalledAgents } from '../../services/agents.service'
import { mockCorePorts } from '../../__tests__/mock-ports'

test('detects custom myagent when configuration directory exists', () => {
  const ports = mockCorePorts({
    fs: {
      existsSync: (path: string) => 
        path.includes('.myagent'),
    },
  })

  const result = detectInstalledAgents(ports)
  expect(result).toContain('myagent')
})

Run the core test suite to verify your changes: npm run test --workspace=@tech-leads-club/core.

Understanding the Runtime Detection Flow

The detectInstalledAgents function (lines 44-50 in agents.service.ts) iterates over all entries in agentDefinitions, executes each detectInstalled function, and returns an array of installed agent types. The CLI UI uses this to pre-select available agents during interactive commands.

The lockfile service (libs/core/src/lib/services/lockfile.service.ts, lines 8-15) stores installation records using the AgentType union. By extending AGENT_TYPES, you automatically enable the lockfile schema to track skills installed for your custom agent without modifying the lockfile service code.

Summary

• Extend AGENT_TYPES in libs/core/src/lib/types.ts to register the compile-time identifier for your custom agent.
• Define runtime configuration in libs/core/src/lib/services/agents.service.ts with display metadata, skill directory paths, and a detectInstalled function.
• Leverage VS Code extension detection using isExtensionInstalled for agents distributed as extensions.
• Validate automatically through the CLI, which checks all arguments against the updated AGENT_TYPES array.
• Test detection logic by mocking filesystem ports in the agents service test suite.

Frequently Asked Questions

Do I need to modify CLI source code to accept a new agent?

No. The CLI commands in packages/cli/src/cli/install.ts and remove.ts import AGENT_TYPES directly and validate arguments against this array. Once you add your agent to the types file, the CLI automatically recognizes it as a valid --agent option.

How does the system determine if an agent is installed?

The detectInstalledAgents function executes the detectInstalled callback defined in each agent's configuration. This function receives filesystem access ports and path utilities, allowing you to check for configuration directories, binaries, or VS Code extension installations specific to your agent.

Can I add support for a proprietary or internal AI agent?

Yes. The architecture supports any agent that can be detected via filesystem checks or extension queries. Simply provide the appropriate detectInstalled logic—whether checking for a custom binary in $HOME/.local/bin, a configuration folder, or a corporate VS Code extension ID.

What happens if I add an agent definition but forget to update AGENT_TYPES?

TypeScript will report compilation errors because the AgentType union won't include your new identifier, but the agentDefinitions record requires keys of type AgentType. The getAgentConfig function and lockfile schema also rely on this type, so both runtime and compile-time checks enforce synchronization between the two files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}