ADR 017: Agent Skills Framework Adoption for A2A Protocol Parity

ADR-017: Agent Skills Framework Adoption for A2A Protocol Parity

Status: Accepted Date: 2025-12-20 Deciders: Hal Casteel, CODITECT Core Team Categories: Architecture, Standards Compliance, Interoperability, Agent Skills

Context

Industry Standardization Moment (2024-2025)

The agent ecosystem is experiencing a once-in-a-decade standardization moment similar to:

2006: REST APIs standardization
2015: Docker containerization
2017: Kubernetes orchestration
2025: Agent + Skills standardization ← We are here

Four major standards have emerged that will define the next generation of agentic platforms:

A2A Protocol (Google, Linux Foundation) - Agent-to-agent communication standard with Agent Cards
Agent Skills Framework (Anthropic) - Portable, token-efficient skill definitions with 3-level progressive disclosure
MCP (Model Context Protocol) (Anthropic) - Agent-to-tool integration (97M+ monthly SDK downloads)
Enterprise Role-Based Patterns (Salesforce, ServiceNow, SAP) - Agents as specialized employees with discoverable skills

CODITECT Current State

Inventory (December 2025):

122 Agents - Specialized AI personas for domain-specific tasks
134 Commands - User-facing slash command entry points
91 Skills - Reusable capability modules
1,149 Workflows - Automation sequences

Critical Gap Identified:

Skills (91) represent only 75% of agents (122)
Skill-to-Agent ratio: 0.75:1 vs. industry-recommended 1.5:1+
Existing skills work correctly but are CODITECT-specific, not portable
No progressive disclosure - full skill loaded every time (~4,500 tokens)
No A2A Protocol integration - agents cannot be discovered by external systems

The Strategic Imperative

User Directive: "I want full A2A parity with a consistent architecture always standard compliant and inter-operable"

This requires transforming CODITECT from a monolithic agent framework to a composable agent + skills ecosystem aligned with emerging standards.

Decision

Adopt the Agent Skills Framework and A2A Protocol as the foundation for all CODITECT agents and skills, with the following commitments:

1. Agent Skills Framework Compliance (P0)

All 91+ skills MUST support:

3-Level Progressive Disclosure:
- Level 1: Skill Card (~20 tokens) - Name + 1-line description
- Level 2: Skill Summary (~150 tokens) - Capabilities + examples
- Level 3: Full Specification (4,000-5,000 tokens) - Complete implementation
Standard JSON Schema per Anthropic specification
Backward Compatibility with existing YAML frontmatter format
Token Budget Enforcement (specify per-skill limits)

2. A2A Protocol Integration (P0)

All 122 agents MUST have:

Agent Cards - JSON capability declarations
Skill References - Links to composable skills
Protocol Declaration - Support for A2A-1.0 and MCP-1.0
Discoverable via Registry - Auto-discovery by external systems

3. Skill-to-Agent Ratio Target (P0)

Metric	Current	Phase 1 Target	Phase 2 Target
Skill:Agent Ratio	0.75:1	1.5:1	2:1+
Total Skills	91	183+	244+
Portable Skills	~20%	60%	90%

4. Backward Compatibility (Non-Negotiable)

Existing skills and agents MUST continue to work without modification. The Agent Skills Framework is an additive extension, not a replacement:

# Existing format (100% compatible)
---
name: skill-name
description: Skill description
allowed-tools: [Read, Write, Edit, Bash]
metadata:
  token-budget: "4500"
---

# Extended format (backward compatible)
---
name: skill-name
description: Skill description
allowed-tools: [Read, Write, Edit, Bash]
metadata:
  token-budget: "4500"

# Optional Agent Skills Framework extension
agent_skills_framework:
  enabled: true
  version: "1.0"
  skill_id: "coditect:skill-name:v1.0"
  capabilities: [...]
  composable_with: [...]
---

Architecture

Four-Layer Composable Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: COMMANDS (User Entry Points)                          │
│  └─ 134 slash commands                                          │
│  └─ Natural language intent mapping                             │
│  └─ Routes to appropriate agent                                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Routes to
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: AGENTS (Roles/Personas)                               │
│  └─ 122 specialized agents                                      │
│  └─ Each has A2A Agent Card                                     │
│  └─ Composes 1-5 skills per task                                │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Composes
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: SKILLS (Portable Capabilities)                        │
│  └─ 183+ skills (target)                                        │
│  └─ 3-level progressive disclosure                              │
│  └─ Cross-agent reusable                                        │
│  └─ Standards-compliant (Agent Skills Framework)                │
└───────────────────────────┬─────────────────────────────────────┘
                            │ Executes
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 4: WORKFLOWS (Multi-Step Processes)                      │
│  └─ 1,149 workflow definitions                                  │
│  └─ State machine orchestration                                 │
│  └─ Complex automation sequences                                │
└─────────────────────────────────────────────────────────────────┘

A2A Agent Card Schema

{
  "agent_card": {
    "id": "coditect:devops-engineer",
    "name": "DevOps Engineering Specialist",
    "version": "1.0.0",
    "description": "CI/CD, container orchestration, and infrastructure automation",
    "protocols": ["A2A-1.0", "MCP-1.0"],
    "capabilities": [
      "cicd-pipeline-design",
      "container-orchestration",
      "infrastructure-as-code",
      "monitoring-observability"
    ],
    "skills": [
      {
        "id": "cicd-pipeline-design",
        "uri": "coditect://skills/cicd-pipeline-design/v1.0",
        "token_budget": 4800
      },
      {
        "id": "container-orchestration",
        "uri": "coditect://skills/container-orchestration/v1.0",
        "token_budget": 5000
      }
    ],
    "contact": "coditect://agents/devops-engineer/invoke"
  }
}

Progressive Disclosure Example

Level 1 - Skill Card (20 tokens):

{
  "skill_id": "coditect:cicd-pipeline-design:v1.0",
  "name": "CI/CD Pipeline Design",
  "description": "GitHub Actions, GitLab CI, deployment strategies"
}

Level 2 - Skill Summary (150 tokens):

{
  "skill_id": "coditect:cicd-pipeline-design:v1.0",
  "name": "CI/CD Pipeline Design",
  "capabilities": [
    "Multi-stage pipeline design (build, test, deploy)",
    "GitHub Actions workflow automation",
    "GitLab CI/CD configuration",
    "Blue-green and canary deployment strategies",
    "Container registry integration"
  ],
  "tools": ["GitHub Actions", "GitLab CI", "Cloud Build", "Docker"],
  "token_budget": 4800
}

Level 3 - Full Specification (4,800 tokens):

{
  "skill_id": "coditect:cicd-pipeline-design:v1.0",
  "full_specification": "[Complete skill implementation with code examples]"
}

Token Efficiency: 4,800 → 20 tokens = 99.6% reduction for discovery phase

Implementation Plan

Phase 1: Foundation (Immediate - 4 Weeks)

Week 1-2: Standards & Schema

Create CODITECT-STANDARD-AGENT-SKILLS-FRAMEWORK.md
Create agent-skills-schema.json (JSON Schema for validation)
Create extracted-skills-registry.json (registry of converted skills)
Pilot: Extract 10 skills from 3 agents (devops-engineer, security-specialist, senior-architect)

Week 3-4: Full Skill Extraction

Extract 92+ additional skills to reach 183+ total
Create Agent Cards for all 122 agents
Implement progressive disclosure for all skills
Update skill discovery API

Phase 2: Integration (Q1 2026 - 6 Weeks)

MCP Protocol Integration

Convert tool specifications to MCP format
Implement MCP-compliant tool registry
Enable external MCP tool discovery

Event-Driven Triggers

Build event bus infrastructure
Create pattern-matching trigger engine
Implement auto-agent activation

Phase 3: Ecosystem (Q2 2026 - 8 Weeks)

Peer-to-Peer A2A Collaboration

Implement agent negotiation protocol
Create collaborative decision-making patterns

Skill Marketplace

Build public skill registry
Create skill import/export APIs
Implement validation and security

Rationale

Why Agent Skills Framework?

Factor	Without Framework	With Framework
Token Usage	364,500 tokens (full load)	4,880 tokens (discovery)
Discovery Speed	Manual search	Automatic registry
Portability	CODITECT-only	Cross-platform
Reusability	Limited	Composable

Decision: The 98.5% token reduction and cross-platform portability justify adoption.

Why A2A Protocol?

The A2A Protocol is backed by Google and the Linux Foundation, with adoption by 150+ organizations. It provides:

Agent Cards - Standard capability discovery
Task Lifecycle - Standardized states (requested, accepted, in-progress, completed)
Inter-Agent Communication - Agents can delegate to each other

Decision: A2A is becoming the HTTP of agent communication. Not adopting would create vendor lock-in.

Why 1.5:1 Skill-to-Agent Ratio?

Industry Best Practice (Salesforce Agentforce, ServiceNow, SAP Joule):

Specialists: 1 core skill minimum
Generalists: 3-5 skills average
Orchestrators: Coordinate skills, minimal direct skills

CODITECT's current 0.75:1 ratio means agents have embedded, non-reusable capabilities. The 1.5:1 target enables:

Skill reuse across agents (60% less redundancy)
Dynamic capability composition
External skill import/export

Consequences

Positive

Standards Compliance - Full A2A and Agent Skills Framework compliance
Token Efficiency - 98.5% reduction in skill discovery phase
Portability - Skills work across Anthropic, Microsoft, OpenAI ecosystems
Composability - Agents dynamically compose skills per task
Discovery - External systems can find and invoke CODITECT agents
Future-Proof - Aligned with industry direction for next decade

Negative

Implementation Effort - 92+ skills to extract and convert
Complexity - More moving parts (registry, discovery API, schema validation)
Migration Risk - Existing integrations may need updates

Mitigations

Risk	Mitigation
Breaking changes	Backward compatibility layer (existing format works)
Implementation time	Phased rollout with pilot first
Complexity	Encapsulated in framework, abstracted by commands

Metrics & Success Criteria

Phase 1 Success (4 weeks)

Metric	Target	Measurement
Skills Created	183+	`config/component-counts.json`
Skill:Agent Ratio	1.5:1	183 / 122 = 1.5
Agent Cards	122	All agents have cards
Progressive Disclosure	100%	All skills support 3 levels

Phase 2 Success (10 weeks cumulative)

Metric	Target	Measurement
MCP Integration	Complete	Tool registry operational
Event Triggers	80% workflows	Auto-trigger coverage
A2A Task Delegation	Operational	Inter-agent tasks work

Phase 3 Success (18 weeks cumulative)

Metric	Target	Measurement
Peer Collaboration	Operational	Design review workflow works
External Skills	10+ imported	Community contributions
Council Patterns	Validated	Multi-agent consensus works

Alternatives Considered

1. Maintain Current Architecture

Continue with 91 skills embedded in agent definitions.

Rejected: Creates vendor lock-in, prevents external discovery, wastes tokens on every skill load.

2. Partial A2A Adoption (Agent Cards Only)

Add Agent Cards without Agent Skills Framework.

Rejected: Agent Cards without progressive disclosure skills provides discovery without efficiency.

3. Custom Standard

Create CODITECT-specific standard instead of adopting A2A/Agent Skills.

Rejected: Would require continuous maintenance as industry standards evolve. Not sustainable.

4. Wait for Standards to Mature

Delay adoption until A2A and Agent Skills Framework stabilize.

Rejected: Both standards are already backed by major players (Google, Anthropic, Linux Foundation). The risk of being left behind exceeds the risk of early adoption.

ADR-014-COMPONENT-CAPABILITY-SCHEMA - How components are indexed
ADR-015-SELF-AWARENESS-FRAMEWORK - How orchestrators discover capabilities
ADR-016-LLM-COUNCIL-PATTERN - Multi-agent consensus patterns
ADR-012-MOE-ANALYSIS-FRAMEWORK - Analysis framework informing this decision

References

Industry Standards:

A2A Protocol - Google/Linux Foundation
Agent Skills Framework - Anthropic (December 2025)
Model Context Protocol - Anthropic (97M+ downloads)

CODITECT Research:

Schemas:

Approved: 2025-12-20 Review Date: 2026-03-20

Context​

Industry Standardization Moment (2024-2025)​

CODITECT Current State​

The Strategic Imperative​

Decision​

1. Agent Skills Framework Compliance (P0)​

2. A2A Protocol Integration (P0)​

3. Skill-to-Agent Ratio Target (P0)​

4. Backward Compatibility (Non-Negotiable)​

Architecture​

Four-Layer Composable Architecture​

A2A Agent Card Schema​

Progressive Disclosure Example​

Implementation Plan​

Phase 1: Foundation (Immediate - 4 Weeks)​

Phase 2: Integration (Q1 2026 - 6 Weeks)​

Phase 3: Ecosystem (Q2 2026 - 8 Weeks)​

Rationale​

Why Agent Skills Framework?​

Why A2A Protocol?​

Why 1.5:1 Skill-to-Agent Ratio?​

Consequences​

Positive​

Negative​

Mitigations​

Metrics & Success Criteria​

Phase 1 Success (4 weeks)​

Phase 2 Success (10 weeks cumulative)​

Phase 3 Success (18 weeks cumulative)​

Alternatives Considered​

1. Maintain Current Architecture​

2. Partial A2A Adoption (Agent Cards Only)​

3. Custom Standard​

4. Wait for Standards to Mature​

Related ADRs​

References​