Fyrtio timmar på att bygga en MCP-server som tjänade kod granskningsförfrågningar, släppte en kollega en markdown-fil i Tio minuter mot fyrtio timmar, samma resultat. .claude/skills/ Den erfarenheten lärde mig något som ingen dokumentation klargör tillräckligt tydligt. Claude Code har tre distinkta förlängningsmekanismer, och de har noll överlappning när du förstår vad var och en faktiskt gör. Bakom dessa tre mekanismer avslöjar en avsiktlig arkitektonisk filosofi som är värt att förstå innan du skriver en enda linje av konfiguration. Designbeslut Arkitekturen bakom tre mekanismer Varje tillägg till Claude Code faller i en av tre kategorier. De existerar som separata mekanismer eftersom de fungerar på fundamentalt olika lager av systemet. Detta är inte oavsiktligt. Svar: "Hur kan Claude komma åt system utanför sin processgräns?" De är separata program som kommunicerar med Claude via JSON-RPC. Modellkontextprotokollet definierar trådformatet (verktygssamtal, resursläsningar, promptmallar), men servern själv är bara ett program som talar JSON över stdio eller HTTP. Det upprätthåller sina egna anslutningar, sitt eget tillstånd, sin egen livscykel. Claude skickar en begäran, servern gör jobbet och skickar tillbaka ett svar. MCP servers Svar: "Hur kör du Claude med olika beteenden för olika uppgifter?" En subagent är en isolerad Claude-session med sin egen systemuppmaning, sitt eget modellval, sin egen verktygsåtkomst och kritiskt sitt eget kontextfönster. När du kallar på en subagent börjar den ny. Ingen ackumulerad kontext från din tidigare konversation. Ingen verktygsåtkomst utöver vad du uttryckligen har beviljat. Subagents Svar: "Hur injicerar du återanvändbar kunskap i en konversation?" En färdighet är en markdown-fil som blir en slash-kommando. När den tillkallas injiceras dess innehåll direkt i den aktuella konversationen som instruktioner. Ingen ny process. Ingen isolering. Ingen separat kontext. Bara text som formar Claude beteende inom den befintliga sessionen. Skills Hur MCP-servrar faktiskt fungerar under locket Modellkontextprotokollet är ett JSON-RPC 2.0-protokoll. När Claude Code startar lanserar den varje konfigurerad MCP-server som en barnprocess och etablerar en tvåvägskommunikationskanal över stdio. När Claude bestämmer sig för att använda ett MCP-verktyg är sekvensen: Claude genererar ett verktygsamtal med ett namn och JSON-argument Claude Code skickar detta som en JSON-RPC-förfrågan till lämplig serverprocess Servern utför begäran (förfrågar en databas, ringer en API, läser ett filsystem) Server returnerar resultatet som ett JSON-RPC-svar Claude Code ger svaret tillbaka till Claude's kontext Detta är genuin inter-process kommunikation. Servern kan skrivas på vilket språk som helst. Det kan upprätthålla ihållande anslutningar till databaser, cache resultat, implementera hastighetsbegränsning, genomdriva åtkomstkontroller. Det är ett verkligt program med verklig status. { "mcpServers": { "analytics": { "command": "node", "args": ["./mcp-servers/analytics.js"], "env": { "DATABASE_URL": "postgresql://localhost/analytics", "MAX_ROWS": "1000", "QUERY_TIMEOUT_MS": "5000" } }, "deploy": { "command": "./mcp-servers/deploy-server", "args": ["--environment", "staging", "--read-only"], "env": { "API_TOKEN": "${DEPLOY_TOKEN}" } } } } den och Miljövariablerna ovan är inte MCP-protokollfunktioner. De är säkerhetsgränser på applikationsnivå som analysservern genomför internt. Detta är en viktig arkitektonisk punkt: MCP-protokollet hanterar kommunikation, men din server hanterar policy. Om Claude ber om varje rad i en tio miljoner rad tabell, kommer protokollet gärna att vidarebefordra den begäran. MAX_ROWS QUERY_TIMEOUT_MS För prestandakritiska integrationer där servern hanterar tusentals förfrågningar eller upprätthåller anslutningspooler är Rust värt investeringen. täcker hela processen från protokollhantering till produktionsutplacering, inklusive anslutningspooling och graciös avstängning. Guide till att bygga MCP-servrar i Rust Remote MCP-servrar över HTTP med SSE följer samma protokoll men ersätter stdio med HTTP-transport. Detta gäller för delad teaminfrastruktur där en enda MCP-serverinstans betjänar flera utvecklare, men det lägger till nätverkslatens och kräver autentisering. Hur underagenter arbetar under huven Subagenter är inte en separat teknik. De är Claude Code-sessioner med begränsade parametrar. När du anropar en subagent startar Claude Code en ny konversation med modellen som anges i agentens konfiguration. Systemkampanjen kommer från markeringskroppen i agentfilen. Verktygslistan filtreras bara till vad agentkonfigurationen tillåter. Och kritiskt sett är kontextfönstret tomt utom för systemkampanjen och den uppgift du har gett subagent. Denna isolering har djupa konsekvenser för både kostnad och kvalitet. Tänk på en debugging session där du har utforskat en kodbas i tjugo minuter. Ditt huvudsakliga kontextfönster innehåller dussintals filläsningar, grep resultat, stack spår och konversation vändningar. Om du nu begär en kodöversyn i samma session, sker översynen i samband med allt det debugging buller. En underagent startar ren. Dess sammanhang innehåller endast systemmeddelandet (dina granskningskriterier) och de filer som du har bett den att granska. inget buller. inget ackumulerat tillstånd. än main-session recensioner, eftersom modellen är helt fokuserad på uppgiften. Bättre --- name: code-reviewer description: Reviews code for quality, security, and style model: haiku tools: Read, Grep, Glob, Bash disallowedTools: Write, Edit mcpServers: - github maxTurns: 15 --- You are a code review specialist. You have read-only access to the codebase and the GitHub API. Review criteria: - No unwrap() in production code paths (use proper error handling) - All public functions have doc comments - Error types implement std::fmt::Display - No println! in library code (use tracing macros) - Integration tests exist for new API endpoints - No TODO without a linked issue number For each file, provide a pass/fail checklist and specific line references for any failures. Do not provide general advice — only specific findings. den För mönstermatchningsarbete som stilkontroll och konventionstillämpning, utför Haiku jämförbart med Opus. model: haiku den Direktivet skapar en hård gräns. Även om systemmeddelandet säger "fixa eventuella problem du hittar", kan underagenten inte ändra filer. disallowedTools: Write, Edit den Förhindrar löpande underagent-sessioner. Utan detta kan en underagent som analyserar en stor kodbas iterera i femtio varv, vilket ackumulerar kostnader. maxTurns: 15 Den verkliga kostnadsmatematiken för modellrutning Det är där underagenterna betalar för sig själva och sedan några. Tänk på ett team av fem utvecklare, var och en kör ungefär tio kod recensioner per dag genom Claude Code. Utan underagenter, kör varje recension i huvud Opus session. Med sammanhang ackumulering från annat arbete, en typisk recension kan konsumera 15.000-25.000 input tokens och generera 2.000-4.000 utdata tokens. Vid Opus prissättning, det är inte trivialt över femtio recensioner per dag. Med en Haiku-subagent körs samma granskning i ett rent kontextfönster. Inmatningstoken sjunker till 3 000- 8 000 (systempropp plus koden som granskas, ingen ackumulerad kontext). Och Haiku: s kostnad per token är dramatiskt lägre än Opus. Den kombinerade effekten av mindre kontext och billigare modell minskar vanligtvis kostnaderna för kod granskning med 85-95%. Men det finns en mer subtil kostnadsfördel. Eftersom subagentkontextfönstren är isolerade och rena, är recensionerna snabbare. Mindre inputkontext innebär mindre bearbetningstid. En Haiku subagent recension returnerar vanligtvis i 2-5 sekunder. Samma recension i en uppblåst Opus session kan ta 10-20 sekunder. Över femtio dagliga recensioner, vilket är betydande tidsbesparingar. Modellrutningsbeslutet är dock inte alltid uppenbart. Vissa uppgifter behöver verkligen Opus-nivå resonemang. Djup debugging sessioner där modellen behöver hålla komplexa tillstånd över många filer. Arkitektonisk analys där modellen behöver resonera om systemomfattande konsekvenser. Refactoring uppgifter där modellen behöver förstå subtila semantiska relationer. Dessa bör stanna på Opus, men i isolerade underagenter så att sammanhanget förblir rent. För den bredare uppsättningen kostnadsstrategier, vår omfattar modellrutning tillsammans med andra tillvägagångssätt som kontexthantering och token-medveten uppmaning. Claude Code kostnadsoptimering guide Hur färdigheter fungerar på Prompt Layer Skills är arkitektoniskt den enklaste mekanismen, och att enkelhet är en funktion. Namnet på katalogen blir slash-kommandot. När du skriver Följ Claude Code Raeds och injicerar innehållet i den aktuella konversationen. .claude/skills/ /review .claude/skills/review/SKILL.md Det finns ingen process. ingen isolering. inget separat kontextfönster. färdighetens text ansluter till din befintliga konversation som om du hade skrivit den själv. Detta innebär att färdigheter drar nytta av konversationens befintliga sammanhang (Claude vet redan vilka filer du har arbetat med) men de ärver också konversationens ackumulerade buller. # SQL Migration Standards Review the migration files for compliance with team standards. ## Naming Conventions - Tables: plural snake_case (user_sessions, not UserSession or user_session) - Columns: singular snake_case (created_at, not CreatedAt) - Indexes: idx_{table}_{columns} (idx_user_sessions_user_id) - Foreign keys: fk_{table}_{referenced_table} (fk_orders_users) ## Safety Requirements - All CREATE INDEX must use CONCURRENTLY - ALTER TABLE ADD COLUMN must include a DEFAULT for non-nullable columns - No DROP COLUMN without a preceding release that stops reading the column - All migrations must be reversible (provide both up and down) ## Query Patterns - Use EXISTS instead of IN for subqueries - Use COALESCE instead of CASE WHEN ... IS NULL - Avoid SELECT * in application code - Always specify column lists in INSERT statements Current schema for reference: $(cat db/schema.sql) Migration to review: $ARGUMENTS den Syntax utför en shellkommando vid invokationstid och injicerar utgången. Detta ger färdigheter begränsad dynamisk förmåga. De kan inkludera filinnehåll, miljövariabler eller kommandoutgång, men de kan inte upprätthålla anslutningar eller utföra flera steg externa operationer. Shellkommandot körs en gång, dess utgång fångas och den statiska texten blir en del av promptet. $(cat db/schema.sql) den variabeln fångar allt efter slash kommandot. skulle sätta till filvägen, så att du kan rikta färdigheten till specifika filer. $ARGUMENTS /migration db/migrations/20260311_add_sessions.sql $ARGUMENTS Färdigheter är kraftfulla just för att de är enkla.Vem som helst kan skriva en.För team där icke-utvecklare behöver koda sin expertis, omfattar hur QA-ingenjörer, produktchefer och tekniska författare skapar effektiva färdigheter utan att röra koden. Kompetens för icke-tekniska team När man INTE ska använda varje mekanism (anti-mönster) Att förstå vad varje mekanism gör bra är bara hälften av bilden. Att veta när man ska undvika var och en förhindrar de misstag jag gjorde tidigt. MCP Server Anti-Pattern användning Om informationen inte ändras mellan invokationer och inte kommer från ett externt system, är det en färdighet. Jag har sett team bygga MCP-servrar som returnerar företagskodningsstandarder, API-dokumentation, till och med stilguider. Do not build an MCP server to serve static content. Claude Code har redan Bash-verktyget. Om din "integration" kör ett CLI-kommando och analyserar utgången behöver du inte en MCP-server. En färdighet som instruerar Claude att använda Bash med specifika kommandon är enklare. Inte allt externt behöver en MCP-server. Om Claude kan köra ett CLI-kommando via Bash är det enklare än att bygga och underhålla en MCP-server. Do not build an MCP server when a Bash tool call would suffice. MCP-servrar är nödvändiga när du behöver fjärrutförande, behörighetsomfattning, ihållande anslutningar eller statliga operationer. eller springa Dessa är CLI-kommandon som Claude kan köra direkt. MCP-servrar tjänar sin komplexitet när flera agenter eller användare behöver delad åtkomst, när du behöver fingrena behörighetskontroller eller när integrationen kräver upprätthållande av status över flera förfrågningar. git log cargo test En MCP-server som utför godtycklig SQL mot produktion är ett lastat vapen. Varje server bör genomdriva frågetid, radgränser, endast läsbar åtkomst där det är lämpligt och inmatningsvalidering. Do not build an MCP server without safety boundaries. Underagent Anti-Patterns Subagenter lyser för upprepad, specialiserat arbete. Om du behöver göra något en gång, gör det bara i huvudsessionen. Överhuvudet för att skapa och underhålla en agentkonfigurationsfil är inte värt det för ad hoc-arbete. Do not create a subagent for a one-off task. Vissa uppgifter kräver verkligen starkare resonemang. Jag försökte köra arkitektonisk analys på Haiku en gång. Det identifierade problem på ytanivå men missade ett cirkulärt beroende som Opus fångade omedelbart. Haiku är briljant för mönstermatchning och checklistning. Det kämpar med uppgifter som kräver flera steg resonemang över många filer. Do not route everything to Haiku to save money. En underagent som åberopar en annan underagent som åberopar en tredje är en anti-mönster. Varje lager lägger till latens och döljer det faktiska arbetet som görs. Om du behöver så mycket orkestrering, omstrukturera ditt tillvägagångssätt. Vanligtvis är svaret en underagent med tillgång till flera MCP-servrar och färdigheter, inte en kedja av underagenter. Do not create deeply nested subagent chains. Färdigheter anti-pattern "Kontrollera produktionsfelfrekvensen" som en färdighetsinstruktion leder Claude till hallucination av mätvärden.Om uppgiften kräver data från utanför Claude-sessionen behöver du en MCP-server (eller en underagent med MCP-åtkomst). Do not write skills that require external data. Innehållet i en färdighet injiceras i kontextfönstret. En färdighet på 5 000 ord förbrukar tokens på varje inbjudan. Håll färdigheter fokuserade. Om du behöver omfattande referensmaterial, använd att villkorligt injicera det i stället för att införliva det direkt i färdigheten. Do not write skills that are too long. $(cat reference.md) En färdighet körs i det aktuella sammanhanget. Om det aktuella sammanhanget är förorenat med orelaterat arbete, minskar färdighetens effektivitet. Uppgifter som behöver en ren platta (recensioner, analyser, dokumentationsgenerering) betjänas bättre av underagenter som börjar med ett nytt kontextfönster. Do not use skills for tasks that need isolation. Kompositionsmodellen i produktionen De tre mekanismerna är inte alternativ. De är lager som komponerar. Att förstå kompositionsmönstren är vad som skiljer en arbetsuppsättning från en elegant. En underagent kan ha MCP-servrar som tilldelats den. Detta skapar omfattande åtkomst. En underagent som granskar kod kan nå GitHubs API via GitHubs MCP-server men kan inte röra din databas eller distributionsrörledning. Databas-analysör subagent laddar sql-standarder skicklighet, så varje analys följer ditt team namngivning konventioner och fråge mönster utan att analytikern subagent behöver dessa konventioner i sin system prompt. Och en underagent har verktygsbegränsningar oberoende av dess MCP-åtkomst.Du kan ge en underagent tillgång till GitHub MCP-servern (så att den kan läsa PR och kommentarer) samtidigt som du inaktiverar Skriv och Redigera (så att den inte kan ändra lokala filer). I vår produktionsuppsättning över 8 marknadsplugins ser lageringen ut så här: Layer 3: Skills (Team Knowledge) /review — code review checklist /migration — database migration standards /deploy-check — pre-deployment verification steps /sql-standards — SQL naming and query conventions /api-design — REST endpoint design patterns Layer 2: Subagents (Specialised Behaviour) code-reviewer (Haiku, read-only, GitHub MCP, review skill) debugger (Opus, full access, all MCP servers) database-analyst (Sonnet, read-only, PostgreSQL MCP, sql-standards skill) deploy-checker (Sonnet, read-only, deploy + analytics MCP, deploy-check skill) doc-writer (Haiku, read-only, no MCP, style-guide skill) Layer 1: MCP Servers (External Connections) analytics-db — PostgreSQL metrics database deploy-pipeline — deployment API wrapper github — GitHub API for PRs and issues content-api — CMS for documentation publishing postgresql — application database (read-only) Varje underagent komponerar exakt de MCP-servrar och färdigheter som den behöver, på modellnivån som matchar dess uppgiftskomplexitet. Deploy-checker använder Sonnet eftersom det behöver argumentera om deploy-beredskap över flera datakällor. De doc-writer använder Haiku eftersom teknisk skrivning är främst mönster matchning mot en stil guide. De debugger använder Opus eftersom debugging verkligen kräver den starkaste resonemang som finns. För fullständig information om hur dessa lager fungerar tillsammans, vår guide på går igenom den kompletta kompositionsmodellen. Och för underagentkonfigurationen specifikt, vår täcker varje frontmatter fält med exempel. Plugins, MCP-servrar och färdigheter som en skiktad arkitektur Anpassad Claude Agent byggnadsguide Beslutets funktion Efter ett år av att bygga produktionsplugins är beslutet en ren funktion av vad du behöver: def choose_mechanism(need): if need.requires_external_data or need.has_side_effects: return "MCP Server" if need.requires_different_model or need.requires_tool_restrictions or need.benefits_from_isolation: return "Subagent" if need.is_reusable_knowledge or need.is_workflow_template: return "Skill" if need.is_complex: return "Subagent + MCP Server + Skill" # compose all three Om du befinner dig att bygga en MCP-server som returnerar statisk text, sluta.Det är en färdighet.Om du skriver en färdighet som säger "fråga databasen", sluta.Det är en MCP-server.Om du kör dyra Opus-sessioner för rutinkontroller, sluta.Det är en subagent på Haiku. Vad har förändrats för oss Innan vi förstod triangeln hade vi MCP-servrar som gjorde färdighetsarbetet, färdigheter som försökte göra MCP-servrarnas arbete och inga underagenter alls. Efter omstrukturering: 34+ färdigheter kodar våra lagkonventioner över kodöversyn, databasarbete, implementering, dokumentation och API-design. Fem underagenter hanterar specialiserade uppgifter vid rätt prispunkt med rätt åtkomstkontroller. Fyra MCP-servrar ansluter till exakt de externa system som behöver anslutas, var och en med rätt säkerhetsgränser. Månadskostnaderna minskade avsevärt. recensionskvaliteten förbättrades eftersom underagenterna började med ett rent sammanhang. Teamkonventioner blev konsekventa eftersom färdigheter tvingar dem på samma sätt för varje utvecklare. Och MCP-servrarna blev enklare eftersom de slutade försöka vara allt; de bara broar till externa system och inget annat. Extensibilitetstriangeln är inte en teoretisk ram. Det är ett praktiskt verktyg som hindrar dig från att bygga fel sak. Vilket, med tanke på att jag byggde fel sak tre gånger innan jag räknade ut detta, är värt att veta om.
