Proposal: Claude Code Extension Compatibility for hve-core

[WilliamBerryiii]

Summary

This proposal describes how to make hve-core compatible with Anthropic's Claude Code extension while maintaining GitHub Copilot (GHCP) as the primary supported tool. The approach uses import-based wrapper files that reference existing GHCP content, preserving a single source of truth.

Background

hve-core currently supports GitHub Copilot through a mature artifact system:

Artifact Type	Location	Count
Instructions	.github/instructions/*.instructions.md	20+
Prompts	.github/prompts/*.prompt.md	18
Agents	.github/agents/*.agent.md	18
Skills	.github/skills/<name>/SKILL.md	1+

Claude Code (extension ID: anthropic.claude-code) uses a different but conceptually similar system:

Claude Code Artifact	Location	Equivalent GHCP Artifact
CLAUDE.md	.claude/CLAUDE.md	copilot-instructions.md
Rules	.claude/rules/*.md	.github/instructions/*.instructions.md
Skills	.claude/skills/<name>/SKILL.md	.github/prompts/*.prompt.md
Subagents	.claude/agents/*.md	.github/agents/*.agent.md

Proposed Approach

Import-Based Wrappers

Claude Code supports @path/to/file syntax for importing content. Rather than duplicating files, create thin wrapper files in .claude/ that import existing GHCP content.

Root Instructions

<!-- .claude/CLAUDE.md -->
# Claude Code Configuration

@.github/copilot-instructions.md

Rules (Instructions)

<!-- .claude/rules/csharp.md -->
@.github/instructions/csharp/csharp.instructions.md

Skills (Prompts)

<!-- .claude/skills/task-research/SKILL.md -->
---
name: task-research
description: Research tasks before implementation planning
context: fork
agent: Explore
---

@.github/prompts/task-research.prompt.md

Subagents (Agents)

<!-- .claude/agents/task-researcher.md -->
---
name: task-researcher
description: Task research specialist for comprehensive project analysis
tools: Read, Grep, Glob, Bash
model: inherit
---

@.github/agents/task-researcher.agent.md

Directory Structure

.claude/
├── CLAUDE.md                           # Root instructions (imports copilot-instructions.md)
├── rules/                              # Rules directory
│   ├── csharp.md                       # → .github/instructions/csharp/csharp.instructions.md
│   ├── markdown.md                     # → .github/instructions/markdown.instructions.md
│   ├── python-script.md                # → .github/instructions/python-script.instructions.md
│   └── ...
├── skills/                             # Skills directory
│   ├── task-research/
│   │   └── SKILL.md                    # → .github/prompts/task-research.prompt.md
│   ├── task-plan/
│   │   └── SKILL.md                    # → .github/prompts/task-plan.prompt.md
│   └── ...
└── agents/                             # Subagents directory
    ├── task-researcher.md              # → .github/agents/task-researcher.agent.md
    ├── task-planner.md                 # → .github/agents/task-planner.agent.md
    ├── task-implementor.md             # → .github/agents/task-implementor.agent.md
    └── ...

Schema Requirements

New Claude Code Schemas

Create JSON schemas for validating Claude Code frontmatter:

claude-skill-frontmatter.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/microsoft/hve-core/schemas/claude-skill-frontmatter.schema.json",
  "title": "Claude Code Skill Frontmatter Schema",
  "description": "Frontmatter schema for Claude Code SKILL.md files",
  "type": "object",
  "required": ["name", "description"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "minLength": 1,
      "description": "Unique identifier for the skill, invoked via /skill-name"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Brief description of when to use this skill"
    },
    "context": {
      "type": "string",
      "enum": ["append", "fork"],
      "default": "append",
      "description": "How skill content is added - append to conversation or fork to subagent"
    },
    "agent": {
      "type": "string",
      "description": "Subagent to run skill in when context is fork"
    },
    "paths": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Glob patterns for automatic skill activation"
    },
    "allowed-tools": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Tools the skill can use"
    },
    "disable-model-invocation": {
      "type": "boolean",
      "default": false,
      "description": "Inject content without model processing"
    }
  },
  "additionalProperties": false
}

claude-subagent-frontmatter.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/microsoft/hve-core/schemas/claude-subagent-frontmatter.schema.json",
  "title": "Claude Code Subagent Frontmatter Schema",
  "description": "Frontmatter schema for Claude Code subagent .md files",
  "type": "object",
  "required": ["name", "description"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "minLength": 1,
      "description": "Unique identifier for the subagent"
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "When Claude should delegate to this subagent"
    },
    "tools": {
      "type": "string",
      "description": "Comma-separated list of Claude Code tools: Read, Edit, Write, Bash, Grep, Glob"
    },
    "disallowedTools": {
      "type": "string",
      "description": "Tools to explicitly deny"
    },
    "model": {
      "type": "string",
      "enum": ["sonnet", "opus", "haiku", "inherit"],
      "default": "inherit",
      "description": "Model to use for this subagent"
    },
    "permissionMode": {
      "type": "string",
      "enum": ["default", "acceptEdits", "dontAsk", "bypassPermissions", "plan"],
      "description": "Permission handling mode"
    },
    "skills": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Skills to preload into subagent context"
    },
    "hooks": {
      "type": "object",
      "description": "Lifecycle hooks for PreToolUse, PostToolUse, Stop events"
    }
  },
  "additionalProperties": false
}

Schema Mapping Updates

Update scripts/linting/schemas/schema-mapping.json:

{
  "mappings": [
    {
      "pattern": ".github/agents/*.agent.md",
      "schema": "agent-frontmatter.schema.json"
    },
    {
      "pattern": ".github/prompts/*.prompt.md",
      "schema": "prompt-frontmatter.schema.json"
    },
    {
      "pattern": ".github/instructions/**/*.instructions.md",
      "schema": "instruction-frontmatter.schema.json"
    },
    {
      "pattern": ".github/skills/**/SKILL.md",
      "schema": "skill-frontmatter.schema.json"
    },
    {
      "pattern": ".claude/skills/**/SKILL.md",
      "schema": "claude-skill-frontmatter.schema.json"
    },
    {
      "pattern": ".claude/agents/*.md",
      "schema": "claude-subagent-frontmatter.schema.json"
    }
  ]
}

Testing Infrastructure

Validation Script Updates

Extend Validate-MarkdownFrontmatter.ps1 to support Claude Code artifacts:

# Add to FileTypeInfo class
class FileTypeInfo {
    # ... existing properties
    [bool]$IsClaudeSkill
    [bool]$IsClaudeSubagent
    [bool]$IsClaudeRule
}

# Add detection logic
function Get-FileTypeInfo {
    param([string]$RelativePath)
    
    $info = [FileTypeInfo]::new()
    # ... existing detection
    
    $info.IsClaudeSkill = $RelativePath -match '\.claude/skills/.+/SKILL\.md$'
    $info.IsClaudeSubagent = $RelativePath -match '\.claude/agents/.+\.md$'
    $info.IsClaudeRule = $RelativePath -match '\.claude/rules/.+\.md$'
    
    return $info
}

Import Validation

Create Test-ClaudeImports.ps1 to validate wrapper files:

<#
.SYNOPSIS
    Validates Claude Code wrapper files reference valid GHCP source files.
.DESCRIPTION
    Scans .claude/ directory for wrapper files and verifies:
    - Import targets exist
    - Import targets are valid GHCP artifacts
    - Wrapper frontmatter is valid for Claude Code
#>

function Test-ClaudeImportTarget {
    param(
        [string]$WrapperPath,
        [string]$ImportPath
    )
    
    $repoRoot = Get-RepoRoot
    $targetPath = Join-Path $repoRoot $ImportPath
    
    if (-not (Test-Path $targetPath)) {
        return @{
            Valid = $false
            Error = "Import target does not exist: $ImportPath"
        }
    }
    
    return @{ Valid = $true }
}

function Get-ImportsFromFile {
    param([string]$FilePath)
    
    $content = Get-Content $FilePath -Raw
    $imports = [regex]::Matches($content, '@([^\s\r\n]+)')
    return $imports | ForEach-Object { $_.Groups[1].Value }
}

Pester Tests

Create scripts/tests/linting/Test-ClaudeCompatibility.Tests.ps1:

Describe 'Claude Code Compatibility' -Tag 'Integration' {
    BeforeAll {
        $script:RepoRoot = (Get-Item $PSScriptRoot).Parent.Parent.Parent.FullName
        $script:ClaudeDir = Join-Path $script:RepoRoot '.claude'
    }

    Context 'CLAUDE.md root file' {
        It 'Exists at .claude/CLAUDE.md' {
            Test-Path (Join-Path $script:ClaudeDir 'CLAUDE.md') | Should -BeTrue
        }

        It 'Imports copilot-instructions.md' {
            $content = Get-Content (Join-Path $script:ClaudeDir 'CLAUDE.md') -Raw
            $content | Should -Match '@\.github/copilot-instructions\.md'
        }
    }

    Context 'Claude skills' {
        It 'Each skill imports a corresponding GHCP prompt' {
            $skills = Get-ChildItem (Join-Path $script:ClaudeDir 'skills') -Recurse -Filter 'SKILL.md'
            foreach ($skill in $skills) {
                $content = Get-Content $skill.FullName -Raw
                $content | Should -Match '@\.github/prompts/'
            }
        }

        It 'Skill frontmatter is valid' {
            $skills = Get-ChildItem (Join-Path $script:ClaudeDir 'skills') -Recurse -Filter 'SKILL.md'
            foreach ($skill in $skills) {
                $frontmatter = Get-Frontmatter $skill.FullName
                $frontmatter.name | Should -Not -BeNullOrEmpty
                $frontmatter.description | Should -Not -BeNullOrEmpty
            }
        }
    }

    Context 'Claude subagents' {
        It 'Each subagent imports a corresponding GHCP agent' {
            $agents = Get-ChildItem (Join-Path $script:ClaudeDir 'agents') -Filter '*.md'
            foreach ($agent in $agents) {
                $content = Get-Content $agent.FullName -Raw
                $content | Should -Match '@\.github/agents/'
            }
        }

        It 'Subagent tools use Claude Code tool names' {
            $validTools = @('Read', 'Edit', 'Write', 'Bash', 'Grep', 'Glob')
            $agents = Get-ChildItem (Join-Path $script:ClaudeDir 'agents') -Filter '*.md'
            foreach ($agent in $agents) {
                $frontmatter = Get-Frontmatter $agent.FullName
                if ($frontmatter.tools) {
                    $tools = $frontmatter.tools -split ',\s*'
                    foreach ($tool in $tools) {
                        $tool | Should -BeIn $validTools
                    }
                }
            }
        }
    }

    Context 'Import targets exist' {
        It 'All imports reference existing files' {
            $wrappers = Get-ChildItem $script:ClaudeDir -Recurse -Filter '*.md'
            foreach ($wrapper in $wrappers) {
                $imports = Get-ImportsFromFile $wrapper.FullName
                foreach ($import in $imports) {
                    $targetPath = Join-Path $script:RepoRoot $import
                    Test-Path $targetPath | Should -BeTrue -Because "$($wrapper.Name) imports $import"
                }
            }
        }
    }
}

Test Fixtures

Create fixture files in scripts/tests/Fixtures/Claude/:

scripts/tests/Fixtures/Claude/
├── valid-skill.md                      # Valid Claude skill with import
├── valid-subagent.md                   # Valid Claude subagent with import
├── invalid-skill-missing-name.md       # Missing required name field
├── invalid-subagent-bad-tools.md       # Invalid tool names
└── broken-import.md                    # Import to non-existent file

Maintenance Requirements

Ongoing Maintenance Tasks

Task	Frequency	Description
Sync new prompts	Per PR	Create Claude skill wrapper when adding GHCP prompt
Sync new agents	Per PR	Create Claude subagent wrapper when adding GHCP agent
Sync new instructions	Per PR	Create Claude rule when adding GHCP instruction
Validate imports	CI	Run Test-ClaudeImports.ps1 in CI pipeline
Schema updates	As needed	Update Claude schemas when Anthropic changes spec
Breaking change review	Quarterly	Review Claude Code docs for breaking changes

Automation: Wrapper Generation Script

Create scripts/dev-tools/New-ClaudeWrapper.ps1:

<#
.SYNOPSIS
    Generates Claude Code wrapper files from GHCP source artifacts.
.PARAMETER Type
    Artifact type: prompt, agent, or instruction.
.PARAMETER SourcePath
    Path to the GHCP source file.
.EXAMPLE
    New-ClaudeWrapper -Type prompt -SourcePath .github/prompts/task-research.prompt.md
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory)]
    [ValidateSet('prompt', 'agent', 'instruction')]
    [string]$Type,

    [Parameter(Mandatory)]
    [string]$SourcePath
)

function New-SkillWrapper {
    param([string]$SourcePath)
    
    $sourceFrontmatter = Get-Frontmatter $SourcePath
    $skillName = [System.IO.Path]::GetFileNameWithoutExtension($SourcePath) -replace '\.prompt$', ''
    
    $targetDir = ".claude/skills/$skillName"
    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
    
    $content = @"
---
name: $skillName
description: $($sourceFrontmatter.description)
context: append
---

@$SourcePath
"@
    
    Set-Content -Path "$targetDir/SKILL.md" -Value $content
    Write-Host "Created: $targetDir/SKILL.md"
}

function New-SubagentWrapper {
    param([string]$SourcePath)
    
    $sourceFrontmatter = Get-Frontmatter $SourcePath
    $agentName = [System.IO.Path]::GetFileNameWithoutExtension($SourcePath) -replace '\.agent$', ''
    
    # Map GHCP tools to Claude Code tools
    $toolMapping = @{
        'codebase' = 'Read, Grep, Glob'
        'editFiles' = 'Edit, Write'
        'terminalLastCommand' = 'Bash'
        'runInTerminal' = 'Bash'
    }
    
    $claudeTools = 'Read, Grep, Glob, Bash'  # Default set
    
    $content = @"
---
name: $agentName
description: $($sourceFrontmatter.description)
tools: $claudeTools
model: inherit
---

@$SourcePath
"@
    
    $targetPath = ".claude/agents/$agentName.md"
    Set-Content -Path $targetPath -Value $content
    Write-Host "Created: $targetPath"
}

switch ($Type) {
    'prompt' { New-SkillWrapper -SourcePath $SourcePath }
    'agent' { New-SubagentWrapper -SourcePath $SourcePath }
    'instruction' { New-RuleWrapper -SourcePath $SourcePath }
}

CI Integration

Add to .github/workflows/validate.yml:

  claude-compatibility:
    name: Claude Code Compatibility
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Validate Claude imports
        shell: pwsh
        run: |
          ./scripts/linting/Test-ClaudeImports.ps1 -ErrorAction Stop
      
      - name: Validate Claude frontmatter
        shell: pwsh
        run: |
          ./scripts/linting/Validate-MarkdownFrontmatter.ps1 `
            -Paths @('.claude') `
            -EnableSchemaValidation

Migration Plan

Phase 1: Foundation (Week 1)

1. Create .claude/ directory structure.
2. Create CLAUDE.md with import to copilot-instructions.md.
3. Add Claude Code schemas to scripts/linting/schemas/.
4. Update schema-mapping.json.

Phase 2: Wrappers (Week 2)

1. Create New-ClaudeWrapper.ps1 script.
2. Generate wrappers for all 18 prompts → skills.
3. Generate wrappers for all 18 agents → subagents.
4. Generate wrappers for priority instructions → rules.

Phase 3: Testing (Week 3)

1. Create Test-ClaudeImports.ps1.
2. Create Test-ClaudeCompatibility.Tests.ps1.
3. Create fixture files.
4. Integrate into CI pipeline.

Phase 4: Documentation (Week 4)

1. Add Claude Code setup guide to docs/getting-started/.
2. Update CONTRIBUTING.md with Claude wrapper requirements.
3. Add prompt-builder.instructions.md section for Claude artifacts.

Compatibility Considerations

Known Differences

Feature	GHCP	Claude Code	Notes
Tool names	codebase, editFiles	Read, Edit, Write	Requires mapping
Auto-apply	applyTo glob	paths array	Similar behavior
Agent isolation	Shared context	Isolated context	Subagents run separately
Model selection	model field	model field	Different model names
Background execution	Not supported	Supported	Claude-only feature
Hooks	Not supported	PreToolUse, PostToolUse	Claude-only feature

Limitations

1. Tool Mapping: GHCP tools frontmatter uses different tool identifiers. Wrappers define Claude-specific tools separately from GHCP source.

2. Context Isolation: Claude subagents run in isolated context windows. GHCP agents share the main conversation context. Some agents may behave differently.

3. Import Depth: Claude Code may not support nested imports (@file referencing another @file). Keep wrappers single-level.

4. MCP Tools: Claude Code MCP tool names differ from GHCP. MCP-dependent agents need wrapper-level tool definitions.

Open Questions

1. Import Behavior: Does Claude Code support @path imports for local files, or only for CLAUDE.md rules? Testing required.

2. Frontmatter Merge: When a wrapper has frontmatter and imports a file with frontmatter, which takes precedence?

3. Maturity Field: Should Claude wrappers track their own maturity, or inherit from GHCP source?

4. Opt-in vs Default: Should Claude support be opt-in (gitignored .claude/) or committed to the repository?

Decision Requested

This proposal requests approval to:

1. ✅ Add .claude/ directory structure with import-based wrappers.
2. ✅ Create Claude Code frontmatter schemas.
3. ✅ Extend validation infrastructure for Claude artifacts.
4. ✅ Add CI jobs for Claude compatibility validation.
5. ✅ Create wrapper generation tooling for maintenance.

References

• Claude Code Documentation
• Claude Code Skills
• Claude Code Subagents
• VS Code Copilot Custom Instructions

[WilliamBerryiii]

CC/ @agreaves-ms, @katriendg, & @cundernehr