Agent Skill Bridge

Agent-Skill Integration Bridge

Description

Facilitates seamless integration between Claude Skills and the existing Agent framework, enabling skills to invoke agents and vice versa with proper context handoffs.

When to Use This Skill

• When creating a skill that needs to invoke an agent (Builder, Validator, etc.)
• When an agent needs to leverage a skill for specific workflow
• When orchestrating multi-agent workflows that include skills
• When troubleshooting agent-skill communication issues

When NOT to Use This Skill

• For simple single-agent tasks (use agents directly)
• For simple single-skill tasks (use skills directly)
• When no integration is needed

Prerequisites

• Understanding of agent framework (see agent templates)
• Understanding of skill architecture (see skill templates)
• Access to MULTI_AGENT_PLAN.md for orchestration
• Familiarity with both agent configs and SKILL.md formats

Workflow

Phase 1: Integration Planning

Step 1.1: Identify Integration Pattern

Pattern A: Skill Invokes Agent

User Request
↓
Skill (Primary workflow orchestrator)
↓
Agent (Specialized execution)
↓
Back to Skill (Result synthesis)

Pattern B: Agent Invokes Skill

User Request
↓
Agent (Primary workflow orchestrator)
↓
Skill (Specialized automation)
↓
Back to Agent (Continue workflow)

Pattern C: Orchestrator Pattern

User Request
↓
Orchestrator Skill
├→ Agent A (parallel)
├→ Agent B (parallel)
└→ Skill C (depends on A+B)
↓
Results Synthesis

Step 1.2: Define Handoff Protocol

Create handoff specification:

## Handoff Specification

**From**: [Skill/Agent Name]
**To**: [Agent/Skill Name]
**Trigger**: [When handoff occurs]

**Data Transfer:**

```json
{
  "handoff_type": "skill_to_agent | agent_to_skill",
  "source": "source-name",
  "destination": "destination-name",
  "context": {
    "execution_id": "unique-id",
    "phase": "current-phase",
    "data": {
      // Relevant data structure
    }
  },
  "requirements": {
    "agent_role": "builder | validator | scribe | devops | researcher",
    "expected_output": "description of what agent should produce",
    "quality_criteria": ["criterion1", "criterion2"]
  }
}

Return Path:

{
  "source": "agent-name",
  "destination": "skill-name",
  "execution_id": "same-unique-id",
  "status": "success | partial | failure",
  "output": {
    // Agent's produced artifact
  },
  "metadata": {
    "duration": "execution-time",
    "quality_score": "0-100",
    "notes": ["note1", "note2"]
  }
}

### Phase 2: Implementation

#### Step 2.1: Skill-to-Agent Invocation

**In SKILL.md, add agent invocation step:**

Step X: Invoke [Agent Name] Agent

Purpose: [Why agent is needed]

Agent Configuration:

• Role: [builder | validator | scribe | devops | researcher]
• Context Required:
  • [File 1]
  • [File 2]
  • [Variable: value]

Invocation:

Update MULTI_AGENT_PLAN.md:

## Phase [N]: [Agent Name] Execution

**Agent**: [Agent Name] (see `.claude/agents/[agent].md`)
**Trigger**: [Skill Name] skill - Step X
**Input**: [What skill provides]

### Tasks for [Agent Name]:
1. [Task 1 with acceptance criteria]
2. [Task 2 with acceptance criteria]

### Expected Output:
[Detailed description]

### Return to Skill:
After completion, return results to [Skill Name] skill for [next step].

Handoff Message:

---
TO: [Agent Name] Agent
FROM: [Skill Name] Skill
EXECUTION_ID: [skill-exec-id]
PHASE: [current-phase]

**Context Provided:**
- [Context item 1]: [Location/value]
- [Context item 2]: [Location/value]

**Tasks:**
1. [Task 1]
2. [Task 2]

**Acceptance Criteria:**
- [Criterion 1]
- [Criterion 2]

**Return Requirements:**
- Output format: [Specification]
- Handoff location: [Where to place results]
- Notification: Update MULTI_AGENT_PLAN.md when complete

**Questions/Blockers:**
Contact: [Skill maintainer]
---

Wait for Agent Completion:

• Monitor MULTI_AGENT_PLAN.md for status updates
• Agent marks tasks complete
• Results available at specified location

Receive Results:

### Step X+1: Process [Agent Name] Results

Load agent output from [location]

Validate:
- [ ] Output format matches specification
- [ ] Acceptance criteria met
- [ ] No errors reported

IF validation passes:
    Proceed to next step
ELSE:
    Review issues and either:
    - Request agent revision
    - Adapt workflow
    - Escalate to human

#### Step 2.2: Agent-to-Skill Invocation

**In agent config (e.g., `builder.md`), add skill invocation:**

Workflow Pattern: Invoke [Skill Name] Skill

When [condition for skill invocation]:

1. Prepare Skill Input:

Create skill-input.json:
{
  "parameter1": "value1",
  "parameter2": "value2",
  "context": {
    // Relevant context from agent
  }
}

2. Invoke Skill: Reference skill documentation: skills/[skill-name]/SKILL.md

Execute skill with: "Use [skill-name] skill with input from skill-input.json" 3. Receive Skill Output: Skill produces: [expected output]

Validate: - [ ] Output format correct - [ ] Quality standards met - [ ] Integration points clear 4. Continue Agent Workflow: Use skill output to [next agent step]

### Phase 3: Orchestration

#### Step 3.1: Multi-Agent-Skill Orchestration

Create orchestrator configuration in `MULTI_AGENT_PLAN.md`:

Multi-Agent-Skill Orchestration Plan

Workflow: [Workflow Name]

Orchestrator: [Lead Skill or Lead Agent]

Execution Graph:

Phase 1: [Orchestrator Skill] - Requirements Gathering
    ↓
Phase 2: [Architect Agent] - System Design (parallel with Phase 3)
    ↓                              ↓
Phase 3: [Research Skill]     Phase 4: [Builder Agent]
    ↓                              ↓
Phase 5: [Orchestrator Skill] - Synthesis
    ↓
Phase 6: [Validator Agent] - Quality Assurance
    ↓
Phase 7: [PR-Generator Skill] - Finalization

Phase Details:

Phase 1: [Orchestrator Skill] - Requirements

Duration: [X min] Output: Requirements document Next: Triggers Phase 2 and 3 in parallel

Phase 2: [Architect Agent] - Design

Input: Requirements document from Phase 1 Tasks:

• Create ARCHITECTURE.md
• Define component structure Output: Architecture specification Next: Triggers Phase 4

Phase 3: [Research Skill] - Technology Analysis

Input: Requirements document from Phase 1 Tasks:

• Research relevant technologies
• Generate comparison matrix Output: Technology recommendations Next: Merges with Phase 2 output for Phase 4

Phase 4: [Builder Agent] - Implementation

Input:

• Architecture spec from Phase 2
• Tech recommendations from Phase 3 Tasks:
• Implement feature
• Write tests Output: Implemented code Next: Triggers Phase 5

[Continue for all phases...]

Handoff Protocol:

Phase N → Phase N+1:

{
  "from_phase": "N",
  "to_phase": "N+1",
  "handoff_data": {
    "artifacts": ["artifact1.md", "artifact2.js"],
    "context": {},
    "status": "complete",
    "quality_score": 95
  }
}

## Examples

### Example 1: PR Description Skill → Validator Agent

**Scenario**: PR description skill generates description, needs code quality validation

**Integration:**

PR Description Skill - Step 5: Request Validation

After generating PR description:

1. Create validation request:

---
TO: Validator Agent
FROM: PR Description Skill

**Request**: Code quality validation for PR #123

**Files to Review:**
- src/auth/jwt.service.js
- tests/auth/jwt.test.js

**Focus Areas:**
- Test coverage ≥90%
- Security: Token validation
- Performance: No N+1 queries

**Return**: Validation report to `pr-123-validation.md`
---

2. Wait for validator completion
3. Receive validation results:

## Validation Report: PR #123

**Status**: ✅ APPROVED

**Test Coverage**: 94%
**Security**: ✅ No issues
**Performance**: ✅ Optimized

**Recommendation**: Safe to merge

4. Append validation summary to PR description:

## Quality Validation

✅ Automated validation passed
- Test coverage: 94%
- Security scan: Clean
- Performance: Optimized

Validated by: Validator Agent
Report: pr-123-validation.md

### Example 2: Builder Agent → Code Formatter Skill

**Scenario**: Builder implements code, needs consistent formatting applied

**Integration in builder.md:**

After Code Implementation

Step X: Apply Code Formatting

Instead of manual formatting commands, invoke skill:

1. Prepare context:

{
  "files_changed": ["src/**/*.js", "tests/**/*.js"],
  "style_guide": ".eslintrc.json",
  "formatter": "prettier"
}

2. Invoke: "Use code-formatter skill with context from above"
3. Skill returns:

{
  "status": "success",
  "files_formatted": 12,
  "issues_fixed": 45,
  "remaining_issues": 0
}

4. Validate formatting:

npm run lint

5. Commit formatted code:

git add .
git commit -m "style: apply code formatter skill"

### Example 3: Orchestrator Skill Coordinating 3 Agents

**Scenario**: Feature development requiring Architect → Builder → Validator sequence

Feature Implementation Orchestrator Skill

Phase 2: Architecture Planning

Invoke: Architect Agent

Handoff:

---
TO: Architect Agent
FROM: Feature Orchestrator Skill
FEATURE: User Authentication

**Requirements:**
- JWT-based authentication
- Refresh token support
- Rate limiting
- Session management

**Deliverables:**
- ARCHITECTURE.md: Auth system design
- SECURITY.md: Security model
- TECH_STACK.md: Libraries selected

**Timeline**: 2 hours
**Budget**: High priority
---

Wait for: Architect marks complete in MULTI_AGENT_PLAN.md

Phase 3: Implementation

Invoke: Builder Agent

Handoff:

---
TO: Builder Agent
FROM: Feature Orchestrator Skill
SOURCE: ARCHITECTURE.md from Phase 2

**Tasks:**
Implement auth system per architecture spec

**Acceptance:**
- All tests passing
- Code coverage ≥90%
- Follows ARCHITECTURE.md design

**Timeline**: 6 hours
---

Wait for: Builder marks complete

Phase 4: Validation

Invoke: Validator Agent

Handoff:

---
TO: Validator Agent
FROM: Feature Orchestrator Skill
PR: #456

**Review Focus:**
- Security validation
- Test coverage verification
- Performance benchmarking

**Acceptance:**
- Zero critical issues
- Coverage ≥90%
- Performance within targets
---

Receive: Validation report

Phase 5: Synthesis

Orchestrator skill compiles:

• Architecture design
• Implementation code
• Validation results
• PR description

Final Output: Complete feature package ready for merge

## Quality Standards

- Handoffs must include unique execution_id for traceability
- All context required by recipient must be explicitly provided
- Return paths must be clearly defined
- Timeout handling for agent/skill execution
- Graceful degradation if agent/skill unavailable

## Common Pitfalls

### Pitfall 1: Missing Context in Handoff
**Issue**: Agent/skill fails because required context not provided
**Solution**: Always validate context completeness before handoff

Pre-Handoff Checklist

• All required files accessible
• All parameters defined
• Acceptance criteria clear
• Return path specified
• Execution ID assigned

### Pitfall 2: No Timeout Handling
**Issue**: Waiting indefinitely for agent/skill completion
**Solution**: Implement timeout with fallback

Step X: Invoke [Agent] with Timeout

1. Invoke agent
2. Set timeout: 30 minutes
3. IF timeout: Log warning Either:
   • Use partial results
   • Skip this step
   • Request human intervention

### Pitfall 3: Circular Dependencies
**Issue**: Skill A calls Agent B which calls Skill A
**Solution**: Design clear dependency graph, avoid cycles

✅ GOOD: Skill → Agent → Skill (different skill)

❌ BAD: Skill A → Agent → Skill A (circular)

## Version History
- 1.0.0 (2025-11-22): Initial release