Package Exports

@aigentics/agent-toolkit
@aigentics/agent-toolkit/src/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@aigentics/agent-toolkit) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Claude Flow Agent Toolkit

🤖 A comprehensive toolkit for validating, fixing, and managing Claude Flow AI agent systems

Features

🔍 Validation: Comprehensive validation of agent configurations
🔧 Auto-Fix: Automatically fix common configuration issues
📊 Analysis: Deep analysis of agent systems with recommendations
✨ Creation: Create new agents with proper configuration
🎯 Standards: Enforce consistent agent configuration standards

Installation

npm install @aigentics/agent-toolkit

Or use directly with npx:

npx @aigentics/agent-toolkit validate

Usage

Command Line Interface

Validate Agents

# Validate all agents in default directory
agent-toolkit validate

# Validate with custom directory
agent-toolkit validate -d ./my-agents

# Output JSON report
agent-toolkit validate -f json -o validation-report.json

# Verbose output
agent-toolkit validate -v

Fix Agent Issues

# Fix all issues (with backup)
agent-toolkit fix

# Dry run - see what would be fixed
agent-toolkit fix --dry-run

# Fix without creating backups
agent-toolkit fix --no-backup

# Fix specific issues
agent-toolkit fix --tools-format
agent-toolkit fix --type-mismatches

Analyze Agent System

# Analyze agent system
agent-toolkit analyze

# Output analysis as JSON
agent-toolkit analyze -f json -o analysis.json

Create New Agents

# Create a basic agent
agent-toolkit create my-agent

# Create with specific type
agent-toolkit create my-swarm-agent -t swarm

# Interactive creation
agent-toolkit create my-agent -i

# Use a template
agent-toolkit create my-github-agent --template github-integration

Programmatic API

import { 
    AgentValidator, 
    AgentFixer, 
    AgentAnalyzer, 
    AgentCreator 
} from '@aigentics/agent-toolkit';

// Validate agents
const validator = new AgentValidator({
    agentsDir: './.claude/agents'
});
const results = await validator.validateAll();

// Fix issues
const fixer = new AgentFixer({
    dryRun: false,
    backup: true
});
const fixResults = await fixer.fixAll();

// Analyze system
const analyzer = new AgentAnalyzer();
const analysis = await analyzer.analyze();

// Create new agent
const creator = new AgentCreator();
const agent = await creator.create({
    name: 'my-agent',
    type: 'core',
    description: 'My custom agent',
    capabilities: ['task1', 'task2']
});

Configuration Schema

Required Fields

All agents must have these fields in their YAML frontmatter:

name - Agent identifier (kebab-case)
type - Agent type (see valid types below)
color - Hex color code
description - Agent description
version - Semantic version (e.g., 1.0.0)
priority - Priority level (high, medium, low)
capabilities - Array of capabilities
triggers - Activation triggers
tools - Tool access configuration
constraints - Execution constraints
communication - Inter-agent communication
dependencies - Agent dependencies
resources - Resource limits
execution - Execution settings
security - Security configuration
monitoring - Monitoring settings
hooks - Pre/post execution hooks

Valid Agent Types

core - Core functionality agents
swarm - Swarm coordination agents
consensus - Consensus protocol agents
github - GitHub integration agents
testing - Testing and validation agents
architecture - System architecture agents
documentation - Documentation agents
analysis - Code analysis agents
specialized - Domain-specific agents
devops - DevOps and CI/CD agents
optimization - Performance optimization agents
templates - Template and boilerplate agents
data - Data processing agents
hive-mind - Collective intelligence agents
sparc - SPARC methodology agents

Directory Organization

Strict Type Directories

These directories must contain agents matching their type:

core/ → type: core
swarm/ → type: swarm
consensus/ → type: consensus
github/ → type: github
etc.

Functional Directories

These directories can contain agents of any type:

templates/ - Template generators
sparc/ - SPARC methodology agents
specialized/ - Domain-specific agents
hive-mind/ - Collective intelligence
development/ - Development workflow
analysis/ - Analysis and review

Common Issues and Fixes

Tools Format

GitHub agents often have tools in array format. The toolkit automatically converts to object format:

# Before (array)
tools: [Read, Write, Bash]

# After (object)
tools:
  allowed: [Read, Write, Bash]
  restricted: [Task]
  conditional: []

Type Mismatches

The toolkit can fix type mismatches using intelligent mapping:

developer → core
coordinator → swarm
analyst → analysis
etc.

Missing Fields

The toolkit automatically adds missing required fields with sensible defaults based on agent type.

Best Practices

Always validate before deployment
Use consistent naming (kebab-case)
Define clear capabilities for each agent
Set appropriate security constraints
Enable monitoring for production agents
Document agent purpose and usage
Test agents in isolation first

Examples

Validation Success (100%)

📊 Validation Summary:
   ✅ Valid: 68
   ⚠️  Warnings: 0
   ❌ Errors: 0
   📁 Total: 68

📈 Statistics by Agent Type:
   core         | 16 total | 16 valid (100%)
   swarm        | 12 total | 12 valid (100%)
   github       | 16 total | 16 valid (100%)
   ...

Creating a Swarm Coordinator

agent-toolkit create swarm-coordinator \
  -t swarm \
  -d "Coordinates multi-agent swarms" \
  -c "swarm_init,topology_optimization,agent_orchestration"

Contributing

Contributions are welcome! Please ensure all agents pass validation before submitting PRs.

License

MIT