CODITECT STANDARD: Agent Skills Framework Extension

Version: 1.0.0 Status: Production Standard Last Updated: December 20, 2025 Authority: Based on Anthropic Agent Skills + A2A Protocol Standards Scope: Extends CODITECT-STANDARD-SKILLS.md and CODITECT-STANDARD-AGENTS.md Backward Compatibility: 100% compatible with existing agents and skills

1. Executive Summary

This extension adds Agent Skills Framework and A2A Protocol compliance to CODITECT while maintaining full backward compatibility with existing agent and skill definitions.

Key Principle: Existing .md files remain the source of truth. JSON metadata is auto-generated for cross-platform compatibility.

Compliance: Optional enhancement for skills and agents targeting external platform integration.

2. Backward Compatibility Guarantee

2.1 Preserved Formats

Agents (UNCHANGED):

---
name: agent-name
description: Brief description
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet
# Existing context_awareness DNA (CODITECT extension)
context_awareness:
  auto_scope_keywords: [...]
  entity_detection: [...]
---

Skills (UNCHANGED):

---
name: skill-name
description: Brief description
---

2.2 Extended Format (Optional)

Agents with A2A Agent Card metadata:

---
name: agent-name
description: Brief description
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet

# EXISTING: Context awareness DNA
context_awareness:
  auto_scope_keywords: [...]

# NEW (OPTIONAL): Agent Skills Framework extension
agent_skills_framework:
  enabled: true
  version: "1.0"
  skills:
    - cicd-pipeline-design
    - container-orchestration
    - monitoring-observability
  a2a_capabilities:
    streaming: true
    push_notifications: false
---

Skills with progressive disclosure metadata:

---
name: skill-name
description: Brief description

# NEW (OPTIONAL): Agent Skills Framework extension
agent_skills_framework:
  enabled: true
  version: "1.0"
  skill_id: "coditect:skill-name:v1.0"
  category: devops
  token_budget: 3500
  capabilities:
    - capability-1
    - capability-2
  composable_with:
    - other-skill-1
    - other-skill-2
---

3. Progressive Disclosure Levels

Level 1: Skill Card (~20 tokens)

Purpose: Discovery phase - identify relevant skills without loading full content.

Auto-generated from YAML frontmatter:

{
  "skill_id": "coditect:skill-name:v1.0",
  "name": "Skill Name",
  "description": "Brief description from YAML frontmatter"
}

Token Efficiency:

Before: 4500 tokens (full SKILL.md)
After: 20 tokens (card only)
Savings: 99.6%

Level 2: Skill Summary (~150 tokens)

Purpose: Selection phase - provide enough context for skill selection.

Includes:

{
  "skill_id": "coditect:skill-name:v1.0",
  "name": "Skill Name",
  "description": "Brief description",
  "capabilities": ["cap-1", "cap-2", "cap-3"],
  "tools": ["Tool1", "Tool2"],
  "token_budget": 3500,
  "composable_with": ["other-skill"]
}

Level 3: Full Specification

Purpose: Execution phase - load complete skill for task execution.

Source: Existing SKILL.md body (unchanged)

4. A2A Agent Cards

4.1 Agent Card Generation

Agent Cards are auto-generated from existing agent .md files:

Input (existing agent file):

---
name: devops-engineer
description: DevOps automation specialist...
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet
---

Output (generated Agent Card):

{
  "agent_id": "coditect:devops-engineer",
  "name": "DevOps Engineer",
  "description": "DevOps automation specialist...",
  "provider": "CODITECT/AZ1.AI",
  "version": "1.0.0",
  "service_endpoint": "coditect://agents/devops-engineer",
  "skills": [
    {
      "skill_id": "coditect:cicd-pipeline-design:v1.0",
      "name": "CI/CD Pipeline Design",
      "description": "Design and implement CI/CD pipelines"
    }
  ],
  "protocols": ["A2A-1.0", "MCP-1.0"]
}

4.2 Agent Card Location

Standard Path: config/agent-cards/{agent-name}.json

Well-Known URL (future): /.well-known/agents/{agent-name}.json

5. Skill Extraction from Agents

5.1 Extraction Process

Read agent .md file (source of truth)
Identify embedded capabilities from Core Responsibilities and Capabilities sections
Create skill definitions in skills/{skill-name}/SKILL.md format
Generate JSON metadata in config/skills/{skill-name}.json
Update agent-skill mapping in config/agent-skill-mappings.json

5.2 Skill-to-Agent Mapping

File: config/agent-skill-mappings.json

{
  "mappings": [
    {
      "agent_id": "coditect:devops-engineer",
      "skills": [
        "coditect:cicd-pipeline-design:v1.0",
        "coditect:container-orchestration:v1.0",
        "coditect:infrastructure-as-code:v1.0",
        "coditect:monitoring-observability:v1.0"
      ],
      "primary_skills": ["cicd-pipeline-design"],
      "supporting_skills": ["container-orchestration", "infrastructure-as-code"],
      "optional_skills": ["monitoring-observability"]
    }
  ]
}

6. Directory Structure

6.1 New Files (Auto-Generated)

config/
├── agent-skills-schema.json          # JSON Schema definition
├── extracted-skills-registry.json    # Extracted skills with metadata
├── agent-skill-mappings.json         # Agent-to-skill relationships
├── agent-cards/                       # A2A Agent Cards
│   ├── devops-engineer.json
│   ├── security-specialist.json
│   └── senior-architect.json
└── skills/                            # Skill metadata (JSON)
    ├── cicd-pipeline-design.json
    ├── container-orchestration.json
    └── ...

6.2 Existing Files (Unchanged)

agents/
├── devops-engineer.md                # UNCHANGED - source of truth
├── security-specialist.md
└── ...

skills/
├── cicd-pipeline-design/
│   └── SKILL.md                      # UNCHANGED - source of truth
└── ...

7. Integration with Existing Standards

7.1 CODITECT-STANDARD-AGENTS.md

Extends: Section 3.2 Optional Fields

# Added optional field for Agent Skills Framework
agent_skills_framework:
  enabled: true
  version: "1.0"
  skills: [skill-name-1, skill-name-2]
  a2a_capabilities:
    streaming: true
    push_notifications: false

7.2 CODITECT-STANDARD-SKILLS.md

Extends: Section 3.1 YAML Frontmatter

# Added optional fields for Agent Skills Framework
agent_skills_framework:
  enabled: true
  skill_id: "coditect:skill-name:v1.0"
  category: devops
  token_budget: 3500
  capabilities: [cap-1, cap-2]
  composable_with: [skill-1, skill-2]

8. Quality Criteria

8.1 Compliance Checklist

Backward Compatibility (Weight: 50%)

Existing YAML frontmatter preserved
Existing markdown body unchanged
Existing tools/model fields present
No breaking changes to existing agents/skills

Agent Skills Framework (Weight: 30%)

JSON metadata generated correctly
skill_id follows namespace:name:version format
Token budget specified
Capabilities list populated

A2A Protocol (Weight: 20%)

Agent Card JSON valid
skills array populated with Level 1 cards
protocols array includes A2A-1.0
service_endpoint format correct

8.2 Validation

# Validate backward compatibility
python3 scripts/validate-agent.py agents/{agent-name}.md

# Generate Agent Skills Framework metadata
python3 scripts/generate-skill-metadata.py skills/{skill-name}/SKILL.md

# Generate A2A Agent Card
python3 scripts/generate-agent-card.py agents/{agent-name}.md

9. Migration Path

9.1 Phase 1: Metadata Generation (Non-Breaking)

Action: Generate JSON metadata from existing files Impact: Zero changes to existing agents/skills Result: Cross-platform compatibility without modification

9.2 Phase 2: Optional Extension (Opt-In)

Action: Add agent_skills_framework: to YAML frontmatter Impact: Enhanced capabilities for opted-in agents/skills Result: Progressive disclosure and skill composition

9.3 Phase 3: Full Integration (Future)

Action: Integrate with A2A protocol and external platforms Impact: Cross-platform skill sharing Result: Ecosystem participation

10. Examples

10.1 Existing Agent (Unchanged)

---
name: devops-engineer
description: DevOps automation specialist...
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet
context_awareness:
  auto_scope_keywords:
    devops: ["ci/cd", "pipeline", "kubernetes"]
---

You are a DevOps Engineering Specialist...

10.2 Agent with Extension (Opt-In)

---
name: devops-engineer
description: DevOps automation specialist...
tools: Read, Write, Edit, Bash, Grep, Glob, TodoWrite
model: sonnet

context_awareness:
  auto_scope_keywords:
    devops: ["ci/cd", "pipeline", "kubernetes"]

# Agent Skills Framework extension
agent_skills_framework:
  enabled: true
  version: "1.0"
  skills:
    - cicd-pipeline-design
    - container-orchestration
    - infrastructure-as-code
    - monitoring-observability
  a2a_capabilities:
    streaming: true
---

You are a DevOps Engineering Specialist...

10.3 Generated Agent Card

{
  "agent_id": "coditect:devops-engineer",
  "name": "DevOps Engineer",
  "description": "DevOps automation specialist...",
  "provider": "CODITECT/AZ1.AI",
  "version": "1.0.0",
  "service_endpoint": "coditect://agents/devops-engineer",
  "skills": [
    {
      "skill_id": "coditect:cicd-pipeline-design:v1.0",
      "name": "CI/CD Pipeline Design",
      "description": "Design and implement CI/CD pipelines"
    },
    {
      "skill_id": "coditect:container-orchestration:v1.0",
      "name": "Container Orchestration",
      "description": "Kubernetes cluster management and Docker"
    }
  ],
  "a2a_capabilities": {
    "streaming": true,
    "push_notifications": false,
    "extensions": ["forms", "files"]
  },
  "authentication": ["Bearer", "OAuth2"],
  "protocols": ["A2A-1.0", "MCP-1.0"]
}

11. References

11.1 Industry Standards

11.2 CODITECT Standards

12. Version History

Version	Date	Changes	Author
1.0.0	2025-12-20	Initial standard for Agent Skills Framework extension	CODITECT Team

Document Control:

Owner: CODITECT Core Team
Approvers: Technical Lead, CEO
Review Cycle: Quarterly
Next Review: 2026-03-20

1. Executive Summary​

2. Backward Compatibility Guarantee​

2.1 Preserved Formats​

2.2 Extended Format (Optional)​

3. Progressive Disclosure Levels​

Level 1: Skill Card (~20 tokens)​

Level 2: Skill Summary (~150 tokens)​

Level 3: Full Specification​

4. A2A Agent Cards​

4.1 Agent Card Generation​

4.2 Agent Card Location​

5. Skill Extraction from Agents​

5.1 Extraction Process​

5.2 Skill-to-Agent Mapping​

6. Directory Structure​

6.1 New Files (Auto-Generated)​

6.2 Existing Files (Unchanged)​

7. Integration with Existing Standards​

7.1 CODITECT-STANDARD-AGENTS.md​

7.2 CODITECT-STANDARD-SKILLS.md​

8. Quality Criteria​

8.1 Compliance Checklist​

8.2 Validation​

9. Migration Path​

9.1 Phase 1: Metadata Generation (Non-Breaking)​

9.2 Phase 2: Optional Extension (Opt-In)​

9.3 Phase 3: Full Integration (Future)​

10. Examples​

10.1 Existing Agent (Unchanged)​

10.2 Agent with Extension (Opt-In)​

10.3 Generated Agent Card​

11. References​

11.1 Industry Standards​

11.2 CODITECT Standards​

12. Version History​