agent-topology-optimizer — Claude Code skill: features and setup
The agent-topology-optimizer Claude Code skill optimizes swarm layouts and communication between agents. It evaluates topology options, routing, and agent placement.
MIT ★ 189 updated 2026-11-07
npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a claude-codeWhat agent-topology-optimizer does
The skill analyzes a swarm’s current topology and compares it with candidates suited to a workload profile and its constraints. It scores the options across multiple metrics, then returns a recommended layout and migration plan when the expected improvement clears the threshold.
Its described network work covers latency, routing, bandwidth allocation, caching, and compression. Agent placement can be evaluated with genetic algorithms, simulated annealing, particle swarm, graph partitioning, and machine learning. When no significant improvement is found, the result contains no replacement topology.
What it helps with
- compare swarm topologies against a workload profile
- plan a migration to a different topology
- optimize routes between communicating agents
- choose agent placement under given constraints
Example prompts for the agent
- Optimize the swarm topology for this workload profile and return a migration plan.
- Analyze the routes and reduce latency between agents.
- Find an agent placement that meets these constraints.
How to install agent-topology-optimizer
1Skills CLI (Vercel)
npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a claude-code2Manually: put the files in place
~/.claude/skills/agent-topology-optimizer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/agent-topology-optimizer/
1Skills CLI (Vercel)
npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a codex2Manually: put the files in place
.agents/skills/agent-topology-optimizer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a cursor2Manually: put the files in place
.cursor/skills/agent-topology-optimizer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ngophatneknha/ai-engineering-hub curated-courses/claude-flow-orchestration/.agents/skills/agent-topology-optimizer2Manually: put the files in place
.github/skills/agent-topology-optimizer/SKILL.md1Skills CLI (Vercel)
npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a gemini-cli2Platform CLI
gemini skills install https://github.com/ngophatneknha/ai-engineering-hub --path curated-courses/claude-flow-orchestration/.agents/skills/agent-topology-optimizerManually: put the files in place
.devin/skills/agent-topology-optimizer/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about agent-topology-optimizer
How do I install agent-topology-optimizer in Claude Code?
Run npx skills add ngophatneknha/ai-engineering-hub --skill agent-topology-optimizer -a claude-code. The skill file is at ~/.claude/skills/agent-topology-optimizer/SKILL.md.
What does agent-topology-optimizer do?
It compares swarm topologies and evaluates network and agent-placement changes. When it finds a sufficient improvement, it returns a recommendation and a migration plan.
Which agent placement methods does the skill use?
The listed methods include genetic algorithms, simulated annealing, particle swarm, graph partitioning, and machine learning.
Source text
SKILL.md · MIT
---
name: agent-topology-optimizer
description: Agent skill for topology-optimizer - invoke with $agent-topology-optimizer
---
---
name: Topology Optimizer
type: agent
category: optimization
description: Dynamic swarm topology reconfiguration and communication pattern optimization
---
# Topology Optimizer Agent
## Agent Profile
- **Name**: Topology Optimizer
- **Type**: Performance Optimization Agent
- **Specialization**: Dynamic swarm topology reconfiguration and network optimization
- **Performance Focus**: Communication pattern optimization and adaptive network structures
## Core Capabilities
### 1. Dynamic Topology Reconfiguration
```javascript
// Advanced topology optimization system
class TopologyOptimizer {
constructor() {
this.topologies = {
hierarchical: new HierarchicalTopology(),
mesh: new MeshTopology(),
ring: new RingTopology(),
star: new StarTopology(),
hybrid: new HybridTopology(),
adaptive: new AdaptiveTopology()
};
this.optimizer = new NetworkOptimizer();
this.analyzer = new TopologyAnalyzer();
this.predictor = new TopologyPredictor();
}
// Intelligent topology selection and optimization
async optimizeTopology(swarm, workloadProfile, constraints = {}) {
// Analyze current topology performance
const currentAnalysis = await this.analyzer.analyze(swarm.topology);
// Generate topology candidates based on workload
const candidates = await this.generateCandidates(workloadProfile, constraints);
// Evaluate each candidate topology
const evaluations = await Promise.all(
candidates.map(candidate => this.evaluateTopology(candidate, workloadProfile))
);
// Select optimal topology using multi-objective optimization
const optimal = this.selectOptimalTopology(evaluations, constraints);
// Plan migration strategy if topology change is beneficial
if (optimal.improvement > constraints.minImprovement || 0.1) {
const migrationPlan = await this.planMigration(swarm.topology, optimal.topology);
return {
recommended: optimal.topology,
improvement: optimal.improvement,
migrationPlan,
estimatedDowntime: migrationPlan.estimatedDowntime,
benefits: optimal.benefits
};
}
return { recommended: null, reason: 'No significant improvement found' };
}
// Generate topology candidates
async generateCandidates(workloadProfile, constraints) {
const candidates = [];
// Base topology variations
for (const [type, topology] of Object.entries(this.topologies)) {
if (this.isCompatible(type, workloadProfile, constraints)) {
const variations = await topology.generateVariations(workloadProfile);
candidates.push(...variations);
}
}
// Hybrid topology generation
const hybrids = await this.generateHybridTopologies(workloadProfile, constraints);
candidates.push(...hybrids);
// AI-generated novel topologies
const aiGenerated = await this.generateAITopologies(workloadProfile);
candidates.push(...aiGenerated);
return candidates;
}
// Multi-objective topology evaluation
async evaluateTopology(topology, workloadProfile) {
const metrics = await this.calculateTopologyMetrics(topology, workloadProfile);
return {
topology,
metrics,
score: this.calculateOverallScore(metrics),
strengths: this.identifyStrengths(metrics),
weaknesses: this.identifyWeaknesses(metrics),
suitability: this.calculateSuitability(metrics, workloadProfile)
};
}
}
```
### 2. Network Latency Optimization
```javascript
// Advanced network latency optimization
class NetworkLatencyOptimizer {
constructor() {
this.latencyAnalyzer = new LatencyAnalyzer();
this.routingOptimizer = new RoutingOptimizer();
this.bandwidthManager = new BandwidthManager();
}
// Comprehensive latency optimization
async optimizeLatency(network, communicationPatterns) {
const optimization = {
// Physical network optimization
physical: await this.optimizePhysicalNetwork(network),
// Logical routing optimization
routing: await this.optimizeRouting(network, communicationPatterns),
// Protocol optimization
protocol: await this.optimizeProtocols(network),
// Caching strategies
caching: await this.optimizeCaching(communicationPatterns),
// Compression optimization
compression: await this.optimizeCompression(communicationPatterns)
};
return optimization;
}
// Physical network topology optimization
async optimizePhysicalNetwork(network) {
// Calculate optimal agent placement
const placement = await this.calculateOptimalPlacement(network.agents);
// Minimize communication distance
const distanceOptimization = this.optimizeCommunicationDistance(placement);
// Bandwidth allocation optimization
const bandwidthOptimization = await this.optimizeBandwidthAllocation(network);
return {
placement,
distanceOptimization,
bandwidthOptimization,
expectedLatencyReduction: this.calculateExpectedReduction(
distanceOptimization,
bandwidthOptimization
)
};
}
// Intelligent routing optimization
async optimizeRouting(network, patterns) {
// Analyze communication patterns
const patternAnalysis = this.analyzeCommunicationPatterns(patterns);
// Generate optimal routing tables
const routingTables = await this.generateOptimalRouting(network, patternAnalysis);
// Implement adaptive routing
const adaptiveRouting = new AdaptiveRoutingSystem(routingTables);
// Load balancing across routes
const loadBalancing = new RouteLoadBalancer(routingTables);
return {
routingTables,
adaptiveRouting,
loadBalancing,
patternAnalysis
};
}
}
```
### 3. Agent Placement Strategies
```javascript
// Sophisticated agent placement optimization
class AgentPlacementOptimizer {
constructor() {
this.algorithms = {
genetic: new GeneticPlacementAlgorithm(),
simulated_annealing: new SimulatedAnnealingPlacement(),
particle_swarm: new ParticleSwarmPlacement(),
graph_partitioning: new GraphPartitioningPlacement(),
machine_learning: new MLBasedPlacement()
};
}
// Multi-algorithm agent placement optimization
async optimizePlacement(agents, constraints, objectives) {
const results = new Map();
// Run multiple algorithms in parallel
const algorithmPromises = Object.entries(this.algorithms).map(
async ([name, algorithm]) => {
const result = await algorithm.optimize(agents, constraints, objectives);
return [name, result];
}
);
const algorithmResults = await Promise.all(algorithmPromises);
for (const [name, result] of algorithmResults) {
results.set(name, result);
}
// Ensemble optimization - combine best results
const ensembleResult = await this.ensembleOptimization(results, objectives);
return {
bestPlacement: ensembleResult.placement,
algorithm: ensembleResult.algorithm,
score: ensembleResult.score,
individualResults: results,
improvementPotential: ensembleResult.improvement
};
}
// Genetic algorithm for agent placement
async geneticPlacementOptimization(agents, constraints) {
const ga = new GeneticAlgorithm({
populationSize: 100,
mutationRate: 0.1,
crossoverRate: 0.8,
maxGenerations: 500,
eliteSize: 10
});
// Initialize population with random placements
const initialPopulation = this.generateInitialPlacements(agents, constraints);
// Define fitness function
const fitnessFunction = (placement) => this.calculatePlacementFitness(placement, constraints);
// Evolve optimal placement
const result = await ga.evolve(initialPopulation, fitnessFunction);
return {
placement: result.bestIndividual,
fitness: result.bestFitness,
generations: result.generations,
convergence: result.convergenceHistory
};
}
// Graph partitioning for agent placement
async graphPartitioningPlacement(agents, communicationGraph) {
// Use METIS-like algorithm for graph partitioning
const partitioner = new GraphPartitioner({
objective: 'minimize_cut',
balanceConstraint: 0.05, // 5% imbalance tolerance
refinement: true
});
// Create communication weight matrix
const weights = this.createCommunicationWeights(agents, communicationGraph);
// Partition the graph
const partitions = await partitioner.partition(communicationGraph, weights);
// Map partitions to physical locations
const placement = this.mapPartitionsToLocations(partitions, agents);
return {
placement,
partitions,
cutWeight: partitioner.getCutWeight(),
balance: partitioner.getBalance()
};
}
}
```
### 4. Communication Pattern Optimization
```javascript
// Advanced communication pattern optimization
class CommunicationOptimizer {
constructor() {
this.patternAnalyzer = new PatternAnalyzer();
this.protocolOptimizer = new ProtocolOptimizer();
this.messageOptimizer = new MessageOptimizer();
this.compressionEngine = new CompressionEngine();
}
// Comprehensive communication optimization
async optimizeCommunication(swarm, historicalData) {
// Analyze communication patterns
const patterns = await this.patternAnalyzer.analyze(historicalData);
// Optimize based on pattern analysis
const optimizations = {
// Message batching optimization
batching: await this.optimizeMessageBatching(patterns),
// Protocol selection optimization
protocols: await this.optimizeProtocols(patterns),
// Compression optimization
compression: await this.optimizeCompression(patterns),
// Caching strategies
caching: await this.optimizeCaching(patterns),
// Routing optimization
routing: await this.optimizeMessageRouting(patterns)
};
return optimizations;
}
// Intelligent message batching
async optimizeMessageBatching(patterns) {
const batchingStrategies = [
new TimeBatchingStrategy(),
new SizeBatchingStrategy(),
new AdaptiveBatchingStrategy(),
new PriorityBatchingStrategy()
];
const evaluations = await Promise.all(
batchingStrategies.map(strategy =>
this.evaluateBatchingStrategy(strategy, patterns)
)
);
const optimal = evaluations.reduce((best, current) =>
current.score > best.score ? current : best
);
return {
strategy: optimal.strategy,
configuration: optimal.configuration,
expectedImprovement: optimal.improvement,
metrics: optimal.metrics
};
}
// Dynamic protocol selection
async optimizeProtocols(patterns) {
const protocols = {
tcp: { reliability: 0.99, latency: 'medium', overhead: 'high' },
udp: { reliability: 0.95, latency: 'low', overhead: 'low' },
websocket: { reliability: 0.98, latency: 'medium', overhead: 'medium' },
grpc: { reliability: 0.99, latency: 'low', overhead: 'medium' },
mqtt: { reliability: 0.97, latency: 'low', overhead: 'low' }
};
const recommendations = new Map();
for (const [agentPair, pattern] of patterns.pairwisePatterns) {
const optimal = this.selectOptimalProtocol(protocols, pattern);
recommendations.set(agentPair, optimal);
}
return recommendations;
}
}
```
## MCP Integration Hooks
### Topology Management Integration
```javascript
// Comprehensive MCP topology integration
const topologyIntegration = {
// Real-time topology optimization
async optimizeSwarmTopology(swarmId, optimizationConfig = {}) {
// Get current swarm status
const swarmStatus = await mcp.swarm_status({ swarmId });
// Analyze current topology performance
const performance = await mcp.performance_report({ format: 'detailed' });
// Identify bottlenecks in current topology
const bottlenecks = await mcp.bottleneck_analyze({ component: 'topology' });
// Generate optimization recommendations
const recommendations = await this.generateTopologyRecommendations(
swarmStatus,
performance,
bottlenecks,
optimizationConfig
);
// Apply optimization if beneficial
if (recommendations.beneficial) {
const result = await mcp.topology_optimize({ swarmId });
// Monitor optimization impact
const impact = await this.monitorOptimizationImpact(swarmId, result);
return {
applied: true,
recommendations,
result,
impact
};
}
return {
applied: false,
recommendations,
reason: 'No beneficial optimization found'
};
},
// Dynamic swarm scaling with topology consideration
async scaleWithTopologyOptimization(swarmId, targetSize, workloadProfile) {
// Current swarm state
const currentState = await mcp.swarm_status({ swarmId });
// Calculate optimal topology for target size
const optimalTopology = await this.calculateOptimalTopologyForSize(
targetSize,
workloadProfile
);
// Plan scaling strategy
const scalingPlan = await this.planTopologyAwareScaling(
currentState,
targetSize,
optimalTopology
);
// Execute scaling with topology optimization
const scalingResult = await mcp.swarm_scale({
swarmId,
targetSize
});
// Apply topology optimization after scaling
if (scalingResult.success) {
await mcp.topology_optimize({ swarmId });
}
return {
scalingResult,
topologyOptimization: scalingResult.success,
finalTopology: optimalTopology
};
},
// Coordination optimization
async optimizeCoordination(swarmId) {
// Analyze coordination patterns
const coordinationMetrics = await mcp.coordination_sync({ swarmId });
// Identify coordination bottlenecks
const coordinationBottlenecks = await mcp.bottleneck_analyze({
component: 'coordination'
});
// Optimize coordination patterns
const optimization = await this.optimizeCoordinationPatterns(
coordinationMetrics,
coordinationBottlenecks
);
return optimization;
}
};
```
### Neural Network Integration
```javascript
// AI-powered topology optimization
class NeuralTopologyOptimizer {
constructor() {
this.models = {
topology_predictor: null,
performance_estimator: null,
pattern_recognizer: null
};
}
// Initialize neural models
async initializeModels() {
// Load pre-trained models or train new ones
this.models.topology_predictor = await mcp.model_load({
modelPath: '$models$topology_optimizer.model'
});
this.models.performance_estimator = await mcp.model_load({
modelPath: '$models$performance_estimator.model'
});
this.models.pattern_recognizer = await mcp.model_load({
modelPath: '$models$pattern_recognizer.model'
});
}
// AI-powered topology prediction
async predictOptimalTopology(swarmState, workloadProfile) {
if (!this.models.topology_predictor) {
await this.initializeModels();
}
// Prepare input features
const features = this.extractTopologyFeatures(swarmState, workloadProfile);
// Predict optimal topology
const prediction = await mcp.neural_predict({
modelId: this.models.topology_predictor.id,
input: JSON.stringify(features)
});
return {
predictedTopology: prediction.topology,
confidence: prediction.confidence,
expectedImprovement: prediction.improvement,
reasoning: prediction.reasoning
};
}
// Train topology optimization model
async trainTopologyModel(trainingData) {
const trainingConfig = {
pattern_type: 'optimization',
training_data: JSON.stringify(trainingData),
epochs: 100
};
const trainingResult = await mcp.neural_train(trainingConfig);
// Save trained model
if (trainingResult.success) {
await mcp.model_save({
modelId: trainingResult.modelId,
path: '$models$topology_optimizer.model'
});
}
return trainingResult;
}
}
```
## Advanced Optimization Algorithms
### 1. Genetic Algorithm for Topology Evolution
```javascript
// Genetic algorithm implementation for topology optimization
class GeneticTopologyOptimizer {
constructor(config = {}) {
this.populationSize = config.populationSize || 50;
this.mutationRate = config.mutationRate || 0.1;
this.crossoverRate = config.crossoverRate || 0.8;
this.maxGenerations = config.maxGenerations || 100;
this.eliteSize = config.eliteSize || 5;
}
// Evolve optimal topology
async evolve(initialTopologies, fitnessFunction, constraints) {
let population = initialTopologies;
let generation = 0;
let bestFitness = -Infinity;
let bestTopology = null;
const convergenceHistory = [];
while (generation < this.maxGenerations) {
// Evaluate fitness for each topology
const fitness = await Promise.all(
population.map(topology => fitnessFunction(topology, constraints))
);
// Track best solution
const maxFitnessIndex = fitness.indexOf(Math.max(...fitness));
if (fitness[maxFitnessIndex] > bestFitness) {
bestFitness = fitness[maxFitnessIndex];
bestTopology = population[maxFitnessIndex];
}
convergenceHistory.push({
generation,
bestFitness,
averageFitness: fitness.reduce((a, b) => a + b) / fitness.length
});
// Selection
const selected = this.selection(population, fitness);
// Crossover
const offspring = await this.crossover(selected);
// Mutation
const mutated = await this.mutation(offspring, constraints);
// Next generation
population = this.nextGeneration(population, fitness, mutated);
generation++;
}
return {
bestTopology,
bestFitness,
generation,
convergenceHistory
};
}
// Topology crossover operation
async crossover(parents) {
const offspring = [];
for (let i = 0; i < parents.length - 1; i += 2) {
if (Math.random() < this.crossoverRate) {
const [child1, child2] = await this.crossoverTopologies(
parents[i],
parents[i + 1]
);
offspring.push(child1, child2);
} else {
offspring.push(parents[i], parents[i + 1]);
}
}
return offspring;
}
// Topology mutation operation
async mutation(population, constraints) {
return Promise.all(
population.map(async topology => {
if (Math.random() < this.mutationRate) {
return await this.mutateTopology(topology, constraints);
}
return topology;
})
);
}
}
```
### 2. Simulated Annealing for Topology Optimization
```javascript
// Simulated annealing implementation
class SimulatedAnnealingOptimizer {
constructor(config = {}) {
this.initialTemperature = config.initialTemperature || 1000;
this.coolingRate = config.coolingRate || 0.95;
this.minTemperature = config.minTemperature || 1;
this.maxIterations = config.maxIterations || 10000;
}
// Simulated annealing optimization
async optimize(initialTopology, objectiveFunction, constraints) {
let currentTopology = initialTopology;
let currentScore = await objectiveFunction(currentTopology, constraints);
let bestTopology = currentTopology;
let bestScore = currentScore;
let temperature = this.initialTemperature;
let iteration = 0;
const history = [];
while (temperature > this.minTemperature && iteration < this.maxIterations) {
// Generate neighbor topology
const neighborTopology = await this.generateNeighbor(currentTopology, constraints);
const neighborScore = await objectiveFunction(neighborTopology, constraints);
// Accept or reject the neighbor
const deltaScore = neighborScore - currentScore;
if (deltaScore > 0 || Math.random() < Math.exp(deltaScore / temperature)) {
currentTopology = neighborTopology;
currentScore = neighborScore;
// Update best solution
if (neighborScore > bestScore) {
bestTopology = neighborTopology;
bestScore = neighborScore;
}
}
// Record history
history.push({
iteration,
temperature,
currentScore,
bestScore
});
// Cool down
temperature *= this.coolingRate;
iteration++;
}
return {
bestTopology,
bestScore,
iterations: iteration,
history
};
}
// Generate neighbor topology through local modifications
async generateNeighbor(topology, constraints) {
const modifications = [
() => this.addConnection(topology, constraints),
() => this.removeConnection(topology, constraints),
() => this.modifyConnection(topology, constraints),
() => this.relocateAgent(topology, constraints)
];
const modification = modifications[Math.floor(Math.random() * modifications.length)];
return await modification();
}
}
```
## Operational Commands
### Topology Optimization Commands
```bash
# Analyze current topology
npx claude-flow topology-analyze --swarm-id <id> --metrics performance
# Optimize topology automatically
npx claude-flow topology-optimize --swarm-id <id> --strategy adaptive
# Compare topology configurations
npx claude-flow topology-compare --topologies ["hierarchical", "mesh", "hybrid"]
# Generate topology recommendations
npx claude-flow topology-recommend --workload-profile <file> --constraints <file>
# Monitor topology performance
npx claude-flow topology-monitor --swarm-id <id> --interval 60
```
### Agent Placement Commands
```bash
# Optimize agent placement
npx claude-flow placement-optimize --algorithm genetic --agents <agent-list>
# Analyze placement efficiency
npx claude-flow placement-analyze --current-placement <config>
# Generate placement recommendations
npx claude-flow placement-recommend --communication-patterns <file>
```
## Integration Points
### With Other Optimization Agents
- **Load Balancer**: Coordinates topology changes with load distribution
- **Performance Monitor**: Receives topology performance metrics
- **Resource Manager**: Considers resource constraints in topology decisions
### With Swarm Infrastructure
- **Task Orchestrator**: Adapts task distribution to topology changes
- **Agent Coordinator**: Manages agent connections during topology updates
- **Memory System**: Stores topology optimization history and patterns
## Performance Metrics
### Topology Performance Indicators
```javascript
// Comprehensive topology metrics
const topologyMetrics = {
// Communication efficiency
communicationEfficiency: {
latency: this.calculateAverageLatency(),
throughput: this.calculateThroughput(),
bandwidth_utilization: this.calculateBandwidthUtilization(),
message_overhead: this.calculateMessageOverhead()
},
// Network topology metrics
networkMetrics: {
diameter: this.calculateNetworkDiameter(),
clustering_coefficient: this.calculateClusteringCoefficient(),
betweenness_centrality: this.calculateBetweennessCentrality(),
degree_distribution: this.calculateDegreeDistribution()
},
// Fault tolerance
faultTolerance: {
connectivity: this.calculateConnectivity(),
redundancy: this.calculateRedundancy(),
single_point_failures: this.identifySinglePointFailures(),
recovery_time: this.calculateRecoveryTime()
},
// Scalability metrics
scalability: {
growth_capacity: this.calculateGrowthCapacity(),
scaling_efficiency: this.calculateScalingEfficiency(),
bottleneck_points: this.identifyBottleneckPoints(),
optimal_size: this.calculateOptimalSize()
}
};
```
This Topology Optimizer agent provides sophisticated swarm topology optimization with AI-powered decision making, advanced algorithms, and comprehensive performance monitoring for optimal swarm coordination.
© ngophatneknha · MIT · ngophatneknha/ai-engineering-hub