Jak vyrobit sdílenou univerzální AI harness?

Univerzální?

V první řadě je třeba zamyslet se, jaké univerzality chceme dosáhnout. Podporovat všechny nástroje je v současnosti nereálné, protože nám začne vznikat omezený průnik kompatibilit a naše možnosti se budou omezovat. Na našem projektu byl historicky nejvíce používaný Copilot, časem jsme přidali Codex CLI a Claude CLI. V tomto článku se zaměřím hlavně na tyto tři nástroje.

Čeho chceme dosáhnout?

V první řadě rozhodně nechceme naše instrukce nijak duplikovat. Harness by měla být jednoduchá, ale zároveň se bude často měnit – DRY pravidlo je tedy zásadní. Z důvodu bezpečnosti jsem se chtěl vyhnout dynamickému stahování instrukcí z internetu kvůli obavám z útoků na dodavatelský řetězec. Dalším důvodem je také to, že tato řešení jsou často velmi komplikovaná a jejich přidaná hodnota je sporná.

Náš tým spravuje asi 10 git repozitářů, které dohromady tvoří jeden velký projekt. Chtěli jsme tedy vytvořit harness, která by byla snadno sdílená mezi všemi repozitáři.

Základní instrukční soubor

Základní instrukční soubor je jediný soubor, který se načte při každé relaci agenta (často i vícekrát). Tento soubor by měl být specifický pro každý repozitář. Je to místo, kde definujeme, jak se má agent chovat v kontextu daného repozitáře. Protože se načítá vždy, měl by být stručný a generický; tedy relevantní pro každý prompt, který můžeme v kontextu repozitáře použít.

AGENTS.md se postupem času stal standardem, který respektuje většina nástrojů. V naší trojici (Copilot, Codex, Claude) jej nerespektuje pouze Claude (ten bohužel stále trvá na svém CLAUDE.md). Jedno řešení je vytvořit CLAUDE.md jako symlink na AGENTS.md. Nevýhodou ale je, že symlinky se nedají sdílet přes git (bez dodatečné klientské konfigurace na Windows).

Lepším řešením je použití speciální Claude syntaxe @file-import. Pokud agent narazí na relativní cestu k souboru za znakem @, načte celý soubor a vloží ho do svého kontextu. Vytvoříme tedy AGENTS.md soubor, který bude obsahovat všechny naše instrukce a do CLAUDE.md souboru napíšeme pouze @AGENTS.md.

Průnik kompatibilit

Níže je krátký přehled toho, co jednotlivé nástroje podporují a jak se liší:

1) Skilly

Skilly umožňují rozšířit schopnosti agenta o nové specializované znalosti a postupy. Agent si podle stručného popisu sám rozhodne, kdy danou dovednost načíst a použít. Definice skillů je standardizovaná a široce podporovaná. Každý nástroj ale hledá skilly na úrovni repozitáře jinde: Claude v .claude/skills/; Copilot a Codex podporují standardní lokaci .agents/skills.

2) Subagenti

Subagenti jsou samostatně definované role ve vývojovém procesu (tester, reviewer, vývojář, ...). Každý má svůj systémový prompt, sadu povolených nástrojů a případně vlastní model, který se použije. Claude, Copilot i Codex subagenty podporují, ale každý používá zcela jiný způsob jejich konfigurace.

3) Prompty a slash příkazy

Prompty jsou uložené textové šablony s instrukcemi pro agenty, které si uživatel může vyvolat namísto opakovaného psaní. Slash příkazy jsou způsob, jak se dá uložený prompt vyvolat v chatu s agentem (např. /review). Obě tyto funkcionality jsou postupně nahrazovány skilly, protože ty umožňují automatické i explicitní vyvolání dle aktuální potřeby.

4) Instrukce

Instrukce jsou pravidla navázaná jen na konkrétní část repozitáře (typicky přes paths nebo applyTo), takže se agentovi do kontextu přidají pouze tehdy, když pracuje na odpovídajících souborech. Claude (.claude/rules/*.md) i Copilot (.github/instructions/*.instructions.md) instrukce podporují, ale každý má vlastní formát definice. Codex je zatím nepodporuje a řeší podobnou potřebu nepřímo; pomocí hierarchie vnořených AGENTS.md souborů.

5) MCP

MCP (Model Context Protocol) je otevřený standard, který agentovi umožňuje připojit se k externím nástrojům a datovým zdrojům (databáze, API, souborové systémy) přes jednotné rozhraní. Samotný protokol podporují všechny tři nástroje; liší se ale způsob konfigurace. Claude v .mcp.json, VS Code (Copilot) v .vscode/mcp.json, Copilot CLI v .mcp.json, Codex v config.toml.

Standardizace nastavení nástrojů se s postupem času zlepšuje, ale stále existuje mnoho překážek. Jedna z možností je vytvořit skript, který by z jednoho standardního formátu vygeneroval konfigurace pro všechny potřebné nástroje přímo na vývojářském prostředí. Z důvodů vysoké komplexity a určité křehkosti jsme ale tuto možnost zavrhli a hledali jsme jiná řešení.

Pluginy jako řešení?

Agentní pluginy jsou mechanismus, který umožňuje sdílet nastavení, aniž by se musely jednotlivé soubory kopírovat nebo duplikovat. Poměrně nedávno (6. 8. 2026) byl vydán nový otevřený standard pro organizaci agentních pluginů. Standard zatím podporuje pouze definice skillů a MCP serverů.

Bohužel se opět opakuje situace s AGENTS.md, protože Anthropic tento standard nepodporuje a trvá na své Claude plugin definici. Vzniká nám tak poměrně komplikovaná matice, protože Claude plugin formát podporuje velké množství nástrojů (ve formě kompatibilních anebo legacy vrstev):

Pokud tedy chceme tento mechanismus použít a současně podporovat všechny tři nástroje (Claude, Codex, Copilot), musíme se spokojit pouze se skilly a MCP servery a musíme mít manifest pluginu definovaný v obou těchto formátech.

Velkou nevýhodou standardu Agent Plugins je, že definuje pouze formát manifestu samotného pluginu. Vůbec tedy neřeší, jak by se plugin měl instalovat a distribuovat. V případě naší harness je to zásadní problém, protože chceme, aby se plugin instaloval automaticky při prvním otevření nástroje nad repozitářem v každém nástroji, který použijeme.

Vytvoření harness repozitáře

Protože chceme harness sdílet mezi více repozitáři, je vhodné ji oddělit od zbytku projektu a vytvořit pro ni samostatný repozitář. Vytvořil jsem ukázkový repozitář jako minimalistický příklad, který definuje sdílenou harness podporující Claude a Agent Plugins 1.0 standardy. Repozitář obsahuje příklad skillu a MCP serveru pro demonstraci funkčnosti. Struktura repozitáře je následující (repozitář s příkladem sdílené harness je dostupný na Githubu):

Všimněte si, že definice skillů a MCP serverů je sdílená mezi oběma formáty. Liší se pouze omáčka okolo: manifesty pluginů a jejich umístění. Manifesty obou pluginů jsou velmi podobné. Úmyslně jsem zvolil různé názvy, aby bylo možné zjistit, který se prioritně načítá.

Manifest pluginu podle standardu Agent Plugins se definuje souborem plugin.json:

{
    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name": "example-plugin",
    "version": "1.0.4",
    "description": "Example plugin for the agent-plugins.org standard.",
    "author": {
        "name": "Ondra Květ"
    },
    "license": "MIT",
    "repository": "https://github.com/ondrej-kvet/shared-ai-harness-example"
}

Claude manifest se definuje souborem .claude-plugin/plugin.json:

{
    "name": "claude-plugin-example",
    "version": "1.0.4",
    "description": "Example plugin for Claude.",
    "author": {
        "name": "Ondra Květ"
    },
    "mcpServers": "./claude.mcp.json"
}

Definice Claude pluginu musí obsahovat i manifest pro katalog. Soubor, který definuje, jaké pluginy repozitář obsahuje a odkud se mají číst:

{
    "name": "shared-ai-harness-example",
    "description": "Example marketplace plugin for Claude.",
    "owner": {
        "name": "Ondra Květ"
    },
    "plugins": [
        {
            "name": "claude-plugin-example",
            "source": "./",
            "description": "Example plugin for Claude."
        }
    ]
}

Tento soubor je současně největší rozdíl mezi oběma formáty, protože standard Agent Plugins žádný koncept katalogu nezná.

Použití harness repozitáře

Obecně je možné pluginy instalovat na třech různých úrovních (byť platí, že ne každý nástroj podporuje všechny tři úrovně):

• Repozitář: plugin je dostupný pro všechny uživatele, kteří repozitář otevřou (vhodné pro sdílené harness).
• Uživatel: plugin je dostupný pro všechny repozitáře, které uživatel otevře (vhodné pro personalizaci).
• Organizace: plugin je dostupný pro všechny repozitáře v rámci organizace.

V příkladu si ukážeme použití harness na úrovni repozitáře. Vytvořil jsem tedy ještě jeden repozitář, který naši harness konzumuje (je také dostupný na Githubu).

Jak již bylo zmíněno výše, jednotlivé nástroje mají různé způsoby instalace a chovají se různě:

1) Claude CLI

Claude umožňuje plugin automaticky zapnout; tohle nastavení ale jen uživateli po spuštění nabídne instalaci pluginu (automatická instalace se nekoná).

Plugin se konfiguruje v souboru .claude/settings.json:

 {
        "enabledPlugins": {
            "claude-plugin-example@shared-ai-harness-example": true
        },
        "extraKnownMarketplaces": {
            "shared-ai-harness-example": {
                "source": {
                    "source": "github",
                    "repo": "ondrej-kvet/shared-ai-harness-example"
                },
                "autoUpdate": true
            }
        }
    }

2) VS Code (Copilot)

Agentní pluginy se ve VS Code spravují ve společném Extensions view. Automatická instalace pluginu podporovaná není, je potřeba jej ručně instalovat přes filtr @agentPlugins @recommended. Implementace působí nedokonale, protože např. není možné ani zjistit verzi nainstalovaného pluginu.

VS Code podporuje stejnou konfiguraci jako Claude .claude/settings.json. Podporuje i vlastní lokaci na cestě .github/copilot/settings.json (zde očekává stejný formát, jako Claude konfigurace).

3) Copilot CLI

Copilot CLI také podporuje stejnou konfiguraci jako Claude. Plugin je zde po spuštění automaticky nainstalovaný, včetně funkčního MCP serveru.

4) Codex CLI a ChatGPT aplikace

Codex CLI zobrazuje plugin jako dostupný v Repository Codex Plugins (pod příkazem /plugins), ale opět je nutné jej nainstalovat ručně. Parametr INSTALLED_BY_DEFAULT v aktuální verzi nefunguje. ChatGPT aplikace se chová obdobně.

Plugin se konfiguruje v souboru .agents/plugins/marketplace.json:

{
        "name": "repo-marketplace",
        "interface": {
            "displayName": "Repository Codex Plugins"
        },
        "plugins": [
            {
                "name": "example-plugin",
                "source": {
                    "source": "url",
                    "url": "https://github.com/ondrej-kvet/shared-ai-harness-example.git",
                    "ref": "main"
                },
                "policy": {
                    "installation": "INSTALLED_BY_DEFAULT",
                    "authentication": "ON_INSTALL"
                },
                "category": "Productivity"
            }
        ]
    }

V aktuální verzi obě OpenAI aplikace nepodporují instalaci pluginů na úrovni repozitáře. Plugin po instalaci vždy skončí v personal kontextu. Doufejme, že se tato situace do budoucna změní.

Závěrem

Cesta standardizace konfigurace AI nástrojů se zdá být dlouhá a trnitá. Máme za sebou několik vítězství (AGENTS.md, skilly), několik proher (Anthropic a jeho nechuť podporovat standardy) a několik kompromisů (distribuce pluginů). Pro vytvoření nejuniverzálnější a současně jednoduché harness doporučuji řešení nastíněné v příkladech: AGENTS.md s CLAUDE.md jako backup, Claude plugin pro Anthropic a legacy, Agent Plugins standard pro budoucí rozvoj. Zároveň doporučuji sledovat dění okolo agentické standardizace, protože aktuální situace se velmi rychle vyvíjí.

Standardizace je podle mě velmi důležitá. Historie IT průmyslu ukazuje nebezpečí vendor lock-in a jeho cestu ke stagnaci (jako odstrašující příklad můžeme zmínit Internet Explorer).