feat: add recursive agent translation support

- Add --recursive flag to scan nested directories for agents
- Add --source flag to specify custom source directory
- New functions: discoverAgentsRecursive, discoverAgentsFromPath
- Add 13 new tests for recursive discovery
- Update README with agent commands documentation
- Bump version to 1.6.3
This commit is contained in:
Rohit Ghumare
2026-01-25 12:07:52 +00:00
parent 10e8c389e3
commit eadbaff07e
10 changed files with 429 additions and 6 deletions
+23
View File
@@ -53,6 +53,8 @@ skillkit recommend
## What's New in v1.6
- **Recursive Agent Translation**: Batch translate entire directories of agents with `--recursive` flag
- **Custom AI Sub-Agents**: Create, translate, sync, and validate custom AI sub-agents across 17 coding agents
- **Methodology Framework**: 5 ready-to-use frameworks (Agile, TDD, DevOps, Security-First, Documentation-First)
- **Hooks System**: Event-driven skill triggers - auto-activate on commits, file changes, builds
- **Agent Orchestration**: Multi-agent team coordination with leader/teammate roles
@@ -95,6 +97,12 @@ skillkit translate --all --to windsurf
# Preview translation without writing
skillkit translate my-skill --to codex --dry-run
# Batch translate from a custom source directory
skillkit agent translate --source ./my-skills --to cursor
# Recursively translate nested agent directories
skillkit agent translate --source ./kubernetes-skills --to cursor --recursive
```
**Supported Agents:** Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Amp, Clawdbot, Droid, GitHub Copilot, Goose, Kilo, Kiro, Roo, Trae, Windsurf, Universal
@@ -272,6 +280,21 @@ skillkit context init # Initialize project context
skillkit context sync # Sync context to agents
```
### Custom AI Sub-Agents
```bash
skillkit agent list # List all installed agents
skillkit agent show <name> # Show agent details
skillkit agent create <name> # Create a new agent
skillkit agent translate # Translate agents between formats
--source ./path # Source directory or file
--to cursor # Target agent format
--recursive # Scan subdirectories recursively
--dry-run # Preview without writing
skillkit agent sync # Sync agents to target AI agent
skillkit agent validate # Validate agent definitions
```
### Memory System
```bash
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "skillkit",
"version": "1.6.2",
"version": "1.6.3",
"description": "Supercharge AI coding agents with portable skills. Install, translate, and share skills across Claude Code, Cursor, Codex, Copilot & 13 more",
"type": "module",
"bin": {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/agents",
"version": "1.6.2",
"version": "1.6.3",
"description": "Agent adapters for SkillKit - supports 17+ AI coding agents",
"type": "module",
"main": "./dist/index.js",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/cli",
"version": "1.6.2",
"version": "1.6.3",
"description": "CLI commands for SkillKit",
"type": "module",
"main": "./dist/index.js",
+40 -1
View File
@@ -13,6 +13,7 @@ import {
findAllAgents,
findAgent,
discoverAgents,
discoverAgentsFromPath,
validateAgent,
translateAgent,
getAgentTargetDirectory,
@@ -294,9 +295,18 @@ export class AgentTranslateCommand extends Command {
static override usage = Command.Usage({
description: 'Translate agents between AI coding agent formats',
details: `
Translates agent definitions between different AI coding agent formats.
Supports recursive translation for directories with multiple agents.
Use --source to specify a custom source directory with agents.
Use --recursive to scan all subdirectories for agents.
`,
examples: [
['Translate all to Cursor', '$0 agent translate --to cursor'],
['Translate specific agent', '$0 agent translate architect --to cursor'],
['Translate from source directory', '$0 agent translate --source ./my-agents --to cursor'],
['Recursive translation', '$0 agent translate --source ./skills --to cursor --recursive'],
['Dry run', '$0 agent translate --to cursor --dry-run'],
],
});
@@ -308,6 +318,10 @@ export class AgentTranslateCommand extends Command {
required: true,
});
source = Option.String('--source,-s', {
description: 'Source directory or file to translate from',
});
output = Option.String('--output,-o', {
description: 'Output directory',
});
@@ -320,13 +334,38 @@ export class AgentTranslateCommand extends Command {
description: 'Translate all agents',
});
recursive = Option.Boolean('--recursive,-r', false, {
description: 'Recursively scan directories for agents',
});
async execute(): Promise<number> {
const searchDirs = [process.cwd()];
const targetAgent = this.to as AgentType;
// Get agents to translate
let agents: CustomAgent[];
if (this.name) {
if (this.source) {
// Translate from custom source path
const sourcePath = this.source.startsWith('/')
? this.source
: join(process.cwd(), this.source);
if (!existsSync(sourcePath)) {
console.log(chalk.red(`Source path not found: ${sourcePath}`));
return 1;
}
agents = discoverAgentsFromPath(sourcePath, this.recursive);
if (agents.length === 0) {
console.log(chalk.yellow(`No agents found in: ${sourcePath}`));
if (!this.recursive) {
console.log(chalk.dim('Tip: Use --recursive to scan subdirectories'));
}
return 0;
}
} else if (this.name) {
const agent = findAgent(this.name, searchDirs);
if (!agent) {
console.log(chalk.red(`Agent not found: ${this.name}`));
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/core",
"version": "1.6.2",
"version": "1.6.3",
"description": "Core functionality for SkillKit - skill discovery, parsing, and translation",
"type": "module",
"main": "./dist/index.js",
@@ -9,6 +9,8 @@ import { tmpdir } from 'node:os';
import {
discoverAgents,
discoverAgentsForAgent,
discoverAgentsRecursive,
discoverAgentsFromPath,
findAllAgents,
findAgent,
getAgentsDirectory,
@@ -312,4 +314,243 @@ Content.`
expect(stats.disabled).toBe(0);
});
});
describe('discoverAgentsRecursive', () => {
it('should discover agents in nested directories', () => {
// Create nested structure like kubernetes-skills/claude-code/k8s-autoscaling
const rootDir = join(testDir, 'skills');
mkdirSync(join(rootDir, 'k8s-autoscaling'), { recursive: true });
mkdirSync(join(rootDir, 'k8s-security'), { recursive: true });
mkdirSync(join(rootDir, 'k8s-deploy'), { recursive: true });
writeFileSync(
join(rootDir, 'k8s-autoscaling', 'AGENT.md'),
`---
name: k8s-autoscaling
description: Kubernetes autoscaling agent
---
Autoscaling content.`
);
writeFileSync(
join(rootDir, 'k8s-security', 'AGENT.md'),
`---
name: k8s-security
description: Kubernetes security agent
---
Security content.`
);
writeFileSync(
join(rootDir, 'k8s-deploy', 'AGENT.md'),
`---
name: k8s-deploy
description: Kubernetes deployment agent
---
Deploy content.`
);
const agents = discoverAgentsRecursive(rootDir);
expect(agents).toHaveLength(3);
const names = agents.map((a) => a.name);
expect(names).toContain('k8s-autoscaling');
expect(names).toContain('k8s-security');
expect(names).toContain('k8s-deploy');
});
it('should discover deeply nested agents', () => {
const rootDir = join(testDir, 'deep-skills');
mkdirSync(join(rootDir, 'category1', 'subcategory', 'agent-deep'), { recursive: true });
writeFileSync(
join(rootDir, 'category1', 'subcategory', 'agent-deep', 'AGENT.md'),
`---
name: agent-deep
description: Deeply nested agent
---
Deep content.`
);
const agents = discoverAgentsRecursive(rootDir);
expect(agents).toHaveLength(1);
expect(agents[0].name).toBe('agent-deep');
});
it('should discover agents as markdown files', () => {
const rootDir = join(testDir, 'md-skills');
mkdirSync(join(rootDir, 'subdir'), { recursive: true });
writeFileSync(
join(rootDir, 'top-level-agent.md'),
`---
name: top-level-agent
description: Top level agent
---
Content.`
);
writeFileSync(
join(rootDir, 'subdir', 'nested-agent.md'),
`---
name: nested-agent
description: Nested agent
---
Content.`
);
const agents = discoverAgentsRecursive(rootDir);
expect(agents).toHaveLength(2);
const names = agents.map((a) => a.name);
expect(names).toContain('top-level-agent');
expect(names).toContain('nested-agent');
});
it('should skip hidden directories except standard agent paths', () => {
const rootDir = join(testDir, 'hidden-test');
mkdirSync(join(rootDir, '.hidden', 'agents'), { recursive: true });
mkdirSync(join(rootDir, '.claude', 'agents'), { recursive: true });
writeFileSync(
join(rootDir, '.hidden', 'agents', 'hidden-agent.md'),
`---
name: hidden-agent
description: Should be skipped
---
Content.`
);
writeFileSync(
join(rootDir, '.claude', 'agents', 'claude-agent.md'),
`---
name: claude-agent
description: Should be found
---
Content.`
);
const agents = discoverAgentsRecursive(rootDir);
expect(agents).toHaveLength(1);
expect(agents[0].name).toBe('claude-agent');
});
it('should return empty array for non-existent directory', () => {
const agents = discoverAgentsRecursive(join(testDir, 'non-existent'));
expect(agents).toHaveLength(0);
});
});
describe('discoverAgentsFromPath', () => {
it('should discover agent from single file', () => {
mkdirSync(testDir, { recursive: true });
writeFileSync(
join(testDir, 'single-agent.md'),
`---
name: single-agent
description: A single agent file
---
Content.`
);
const agents = discoverAgentsFromPath(join(testDir, 'single-agent.md'));
expect(agents).toHaveLength(1);
expect(agents[0].name).toBe('single-agent');
});
it('should discover agents from directory without recursive flag', () => {
const rootDir = join(testDir, 'flat-dir');
mkdirSync(rootDir, { recursive: true });
writeFileSync(
join(rootDir, 'agent-a.md'),
`---
name: agent-a
description: Agent A
---
Content.`
);
writeFileSync(
join(rootDir, 'agent-b.md'),
`---
name: agent-b
description: Agent B
---
Content.`
);
const agents = discoverAgentsFromPath(rootDir, false);
expect(agents).toHaveLength(2);
});
it('should discover agents from directory with recursive flag', () => {
const rootDir = join(testDir, 'nested-dir');
mkdirSync(join(rootDir, 'subdir'), { recursive: true });
writeFileSync(
join(rootDir, 'agent-top.md'),
`---
name: agent-top
description: Top agent
---
Content.`
);
writeFileSync(
join(rootDir, 'subdir', 'agent-nested.md'),
`---
name: agent-nested
description: Nested agent
---
Content.`
);
const agentsNonRecursive = discoverAgentsFromPath(rootDir, false);
expect(agentsNonRecursive).toHaveLength(1);
expect(agentsNonRecursive[0].name).toBe('agent-top');
const agentsRecursive = discoverAgentsFromPath(rootDir, true);
expect(agentsRecursive).toHaveLength(2);
const names = agentsRecursive.map((a) => a.name);
expect(names).toContain('agent-top');
expect(names).toContain('agent-nested');
});
it('should handle agent directory with AGENT.md', () => {
const agentDir = join(testDir, 'agent-dir');
mkdirSync(agentDir, { recursive: true });
writeFileSync(
join(agentDir, 'AGENT.md'),
`---
name: agent-dir
description: Directory-based agent
---
Content.`
);
const agents = discoverAgentsFromPath(agentDir);
expect(agents).toHaveLength(1);
expect(agents[0].name).toBe('agent-dir');
});
it('should return empty array for non-existent path', () => {
const agents = discoverAgentsFromPath(join(testDir, 'non-existent'));
expect(agents).toHaveLength(0);
});
it('should return empty array for non-markdown file', () => {
writeFileSync(join(testDir, 'not-agent.txt'), 'Not an agent');
const agents = discoverAgentsFromPath(join(testDir, 'not-agent.txt'));
expect(agents).toHaveLength(0);
});
});
});
+118
View File
@@ -263,3 +263,121 @@ export function getAgentStats(searchDirs: string[]): {
disabled: allAgents.filter(a => !a.enabled).length,
};
}
/**
* Recursively discover all agents in a directory tree
* This finds agents at any depth, useful for batch translation
*/
export function discoverAgentsRecursive(
rootDir: string,
location: AgentLocation = 'project'
): CustomAgent[] {
const agents: CustomAgent[] = [];
const seen = new Set<string>();
if (!existsSync(rootDir)) {
return agents;
}
function scanDirectory(dir: string): void {
try {
const entries = readdirSync(dir, { withFileTypes: true });
for (const entry of entries) {
const entryPath = join(dir, entry.name);
if (entry.isFile() && extname(entry.name) === '.md') {
// Parse markdown file directly
const agent = parseAgentFile(entryPath, location);
if (agent && !seen.has(agent.name)) {
seen.add(agent.name);
agents.push(agent);
}
} else if (entry.isDirectory()) {
// Skip hidden directories except standard agent paths
if (entry.name.startsWith('.') && !entry.name.startsWith('.claude') &&
!entry.name.startsWith('.cursor') && !entry.name.startsWith('.codex')) {
continue;
}
// Try to parse as agent directory first
const agent = parseAgentDir(entryPath, location);
if (agent && !seen.has(agent.name)) {
seen.add(agent.name);
agents.push(agent);
} else {
// If not an agent directory, recurse into it
scanDirectory(entryPath);
}
}
}
} catch {
// Ignore errors (permission denied, etc.)
}
}
scanDirectory(rootDir);
return agents;
}
/**
* Discover agents from a custom source path
* Handles both file paths and directories
*/
export function discoverAgentsFromPath(
sourcePath: string,
recursive: boolean = false,
location: AgentLocation = 'project'
): CustomAgent[] {
if (!existsSync(sourcePath)) {
return [];
}
const stats = statSync(sourcePath);
// Single file
if (stats.isFile()) {
if (extname(sourcePath) === '.md') {
const agent = parseAgentFile(sourcePath, location);
return agent ? [agent] : [];
}
return [];
}
// Directory
if (stats.isDirectory()) {
if (recursive) {
return discoverAgentsRecursive(sourcePath, location);
}
// Non-recursive: only check immediate directory
// First try as agent directory
const agent = parseAgentDir(sourcePath, location);
if (agent) {
return [agent];
}
// Otherwise scan directory contents (one level)
const agents: CustomAgent[] = [];
try {
const entries = readdirSync(sourcePath, { withFileTypes: true });
for (const entry of entries) {
const entryPath = join(sourcePath, entry.name);
if (entry.isFile() && extname(entry.name) === '.md') {
const a = parseAgentFile(entryPath, location);
if (a) agents.push(a);
} else if (entry.isDirectory()) {
const a = parseAgentDir(entryPath, location);
if (a) agents.push(a);
}
}
} catch {
// Ignore errors
}
return agents;
}
return [];
}
+2
View File
@@ -41,6 +41,8 @@ export {
discoverAgents,
discoverAgentsForAgent,
discoverGlobalAgents,
discoverAgentsRecursive,
discoverAgentsFromPath,
findAllAgents,
findAgent,
getAgentsDirectory,
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@skillkit/tui",
"version": "1.6.2",
"version": "1.6.3",
"description": "Terminal UI for SkillKit",
"type": "module",
"main": "./dist/index.js",