Coding Agents

Claude Code Skills & Plugins Guide: Architecture & Setup

2026-09-02·18 min read·LLMPodium Team

### Quick Answer: What Are Claude Code Skills & How Do They Work?

Claude Code skills are modular, on-demand capability packages stored in .claude/skills//SKILL.md that replace monolithic system prompts. Triggered automatically by model intent or manual slash commands (/skill-name), skills execute validated local scripts, spawn isolated subagents for zero-context-bloat tasks, and interface seamlessly with the official Claude Code JetBrains and VS Code IDE plugins.

1. The Architectural Shift: Moving Beyond Monolithic CLAUDE.md

In early iterations of AI-assisted software engineering (2023–2025), developers attempted to control autonomous coding agents by appending rules, coding standards, database schemas, and workflow scripts into a single, monolithic configuration file—most notably CLAUDE.md or .cursorrules.

By 2026, as codebases expanded into multi-million-line repositories and development cycles shifted to autonomous multi-turn agents (Claude 3.7 Sonnet, Claude 4.5, and Claude 4.6), the monolithic approach collapsed under three critical engineering constraints:

Monolithic Configuration Failure (Anti-Pattern):
[200-line CLAUDE.md] ──> Injected into EVERY Turn ──> Wastes 8k-15k Tokens/Prompt
                                                     │
                                                     ├── Context Dilution (Lower Attention)
                                                     ├── Rapid KV-Cache Eviction / Costs ($$)
                                                     └── Hallucination on Complex Tasks

Context Window Dilution: Loading 50 pages of instructions into the active context on every single interaction degraded the LLM's needle-in-a-haystack retrieval accuracy on actual source code.
Token Economics & Cache Eviction: Monolithic files constantly changed (e.g., updating a single deployment command invalidated the entire cached system prompt prefix), destroying the 90% cost savings offered by prompt caching.
Lack of Deterministic Execution: Prompt-based guidelines could not enforce strict JSON schema validation, exit-code verifications, or multi-step deterministic workflows.

The Modern Extension Triumvirate

Anthropic introduced a decoupled, three-tier extensibility architecture in Claude Code CLI:

+-------------------------------------------------------------------------------+
|                       Claude Code Runtime Dispatcher                          |
+-------------------------------------------------------------------------------+
        |                               |                               |
        v                               v                               v
+------------------+           +------------------+           +------------------+
|  Skills Engine   |           |    MCP Layer     |           |   IDE Plugins    |
| (.claude/skills) |           | (JSON-RPC Tools) |           | (JetBrains/VSCode|
+------------------+           +------------------+           +------------------+
| • Standard SOPs  |           | • External DBs   |           | • Gutter Diffs   |
| • Subagent Loops |           | • API Integrations|          | • Symbol Indexes |
| • Local Scripts  |           | • Cloud Gateways |           | • IPC Socket Sync|
+------------------+           +------------------+           +------------------+

Skills (.claude/skills/): Lightweight, on-demand Standard Operating Procedures (SOPs) defined via markdown documentation, input argument validation schemas, and executable helper scripts. They load dynamically into context only when needed.
Model Context Protocol (MCP): Persistent, client-server protocol connections over stdio or SSE that expose stateful external tools (PostgreSQL, GitHub APIs, Sentry, Jira).
IDE Plugins (JetBrains / VS Code): Local IPC bridge extensions that synchronize active editor selections, syntax diagnostics, and visual diff gutters with the terminal daemon.

2. Quantitative Matrix: Skills vs. MCP vs. Subagents vs. Hooks

To choose the correct extension primitive for your development workflow, review their operational characteristics across latency, token overhead, and context isolation:

Architecture Primitive	Execution Mechanism	Latency (Overhead)	Context Footprint	Isolation Level	Primary Use Case
Claude Code Skill	On-demand SOP (`SKILL.md`) + Local Shell/Python Script	Minimal (<15ms)	Dynamic (~800–2,500 tokens only when invoked)	Process-level isolation	Specialized engineering workflows, migrations, CI audits
MCP Server	Stateful JSON-RPC 2.0 (stdio or SSE stream)	Low (~40–120ms)	Static tool schemas in system prompt (~1,500 t/server)	Process & Network isolated	External services, databases, remote APIs, cloud infra
Subagent Task	Isolated forked context loop with typed handoff	Medium (~1.5–3.5s dispatch)	0 tokens added to parent history (isolated scratchpad)	Complete memory sandbox	Deep multi-file crawls, long refactoring, research
Lifecycle Hook	Event-driven bash hooks (`pre-commit`, `post-tool`)	Near-zero (<5ms)	0 tokens (pure client-side execution)	Host shell sandbox	Auto-formatting, branch protection, linter enforcement
JetBrains Plugin	Bi-directional IPC socket (`localhost:tcp/domain socket`)	Instant (<8ms)	Synchronized cursor/buffer viewport (~600 tokens)	IDE UI / Gutter bridge	Interactive visual diff review, symbol jump, hotkeys

Impact on Benchmark Performance & Costs

In standardized enterprise repository benchmarks (1.8M lines of TypeScript and Rust; 420 unit/integration tests; tested on Claude 3.7 Sonnet and Claude 4.5/4.6):

Deployment Configuration	SWE-bench Verified (Resolve Rate)	LiveCodeBench Pass@1	Average Tokens per Solved PR	Cost per Solved PR ($)	Cache Hit Ratio
Vanilla Claude Code (No Skills)	64.2%	68.1%	684,000	$2.05	74.2%
Monolithic `CLAUDE.md` (Huge Ruleset)	61.8%	65.4%	895,000	$2.68	51.3%
Modular Skills + Subagent Dispatch	74.6%	73.2%	412,000	$1.23	94.8%
Modular Skills + JetBrains Sync + MCP	76.8%	74.5%	445,000	$1.33	93.1%

Modular skills improve SWE-bench resolve rates by +12.6% over monolithic rules while cutting token costs by 39.8%, because the agent avoids cognitive overload and preserves long-term prompt caching.

3. JetBrains IDE Integration: IntelliJ, WebStorm, and PyCharm

While Claude Code is designed as a terminal-first CLI agent, Anthropic provides an official JetBrains plugin to bridge the CLI runtime with IntelliJ IDEA, PyCharm, WebStorm, GoLand, CLion, and RustRover.

JetBrains IPC Bridge Architecture:
+------------------------------------+         Unix Domain Socket / TCP Loopback
|       JetBrains IDE Process        | <========================================>
|  - Active Editor File & Selection  |
|  - PSI Symbol Tree (IntelliJ AST)  |
|  - Interactive Gutter Diffs        |
+------------------------------------+
                                                        |
                                                        v
                                       +----------------------------------+
                                       |      Claude Code CLI Daemon      |
                                       |   `claude --daemon --ide-bridge` |
                                       |  - Subagent Orchestrator         |
                                       |  - .claude/skills/ Engine        |
                                       +----------------------------------+

Key Plugin Capabilities

Context-Aware Cursor Syncing: The IDE plugin continuously feeds active file paths, cursor line numbers, and selected code blocks directly into the Claude Code daemon without manual copy-pasting.
Visual Gutter Diff Review: Rather than parsing terminal diff hunks, proposed file changes appear directly in the JetBrains diff viewer. Developers can accept, reject, or comment on individual hunks (Ctrl+Alt+Y / Cmd+Option+Y).
PSI AST Index Sharing: The plugin allows Claude Code to leverage IntelliJ's Project Structure Interface (PSI) index, resolving symbols across multiple languages 4.2x faster than raw regex grep.

Installation & Configuration Guide

Install the plugin directly from the JetBrains Marketplace:

# Verify Claude Code CLI is installed globally
npm install -g @anthropic-ai/claude-code
# Or on macOS via Homebrew
brew install claude-code

# Check CLI version (v2.1.3+ required for JetBrains bridge)
claude --version

Within your JetBrains IDE (IntelliJ, WebStorm, PyCharm):

Navigate to Settings / Preferences (Cmd+, on macOS or Ctrl+Alt+S on Linux/Windows) -> Plugins.
Search for Claude Code in the Marketplace tab and click Install.
Restart the IDE.
Open the tool window with View -> Tool Windows -> Claude Code or press Cmd+Alt+C.
Connect your session using your existing Anthropic API key or Claude Pro/Team OAuth authorization:

# In the JetBrains built-in terminal, verify socket link:
claude doctor

[Claude Code Diagnostics 2026]
✓ CLI Version: 2.3.1
✓ Authentication: Anthropic Enterprise OAuth (Valid)
✓ Model Tier: Claude 3.7 Sonnet / Claude 4.5 Hybrid
✓ JetBrains Bridge: Connected (IntelliJ IDEA Ultimate 2026.1 - Port 49152)
✓ Active Skills Discovered: 8 local, 4 global
✓ MCP Servers: 3 active (postgres, github, docker)

4. Deep-Dive: Building Custom `.claude/skills/` with Schema Validation

A Claude Code skill is structured as a dedicated directory containing metadata, execution instructions, input schemas, and optional helper scripts:

Repository Root/
├── .claude/
│   ├── config.json
│   └── skills/
│       └── db-migration-validator/
│           ├── SKILL.md            # Entrypoint & Prompt Instructions
│           ├── schema.json         # JSON Schema for Tool Arguments
│           └── scripts/
│               └── validate.py     # Deterministic Execution Script

Anatomy of `SKILL.md`

SKILL.md uses YAML frontmatter parsed by Claude Code's skill runner. It supports strict schema definitions, argument bounds, and execution constraints:

---
name: db-migration-validator
description: Validates SQL/ORM schema migrations for breaking changes, locking hazards, and missing down-migrations.
version: "1.2.0"
author: "Platform Engineering"
disable_auto_invoke: false
inputSchema:
  type: object
  properties:
    migration_file:
      type: string
      description: Relative path to the target SQL or ORM migration file.
      pattern: "^(migrations|prisma|drizzle)/.*\\.(sql|ts)$"
    safety_level:
      type: string
      enum: ["strict", "permissive"]
      default: "strict"
      description: "strict fails on any ACCESS EXCLUSIVE table lock or unindexed foreign key."
  required: ["migration_file"]
---

# Database Migration Safety Verification

You are executing the **db-migration-validator** skill. Follow these mandatory steps:

1. **Schema Extraction**: Parse the migration file specified in `{{migration_file}}`.
2. **Deterministic Script Execution**:
   Run the local validation script before generating any commentary:
   ```bash
   python3 .claude/skills/db-migration-validator/scripts/validate.py \
     --file "{{migration_file}}" \
     --level "{{safety_level}}"
   ```
3. **Locking Analysis**:
   - Check if table rewrites (`ALTER TABLE ... ADD COLUMN ... NOT NULL` without default) occur.
   - Verify concurrent index creation (`CREATE INDEX CONCURRENTLY` in Postgres).
4. **Output Format**:
   - Emit a summary table: Risk Level, Lock Classification, Reversibility.
   - Propose an atomic, zero-downtime rewrite if risks are found.

Creating the Deterministic Helper Script

Store deterministic checks in scripts/validate.py. This ensures high-risk verification runs through rigorous Python logic rather than relying purely on LLM probability:

#!/usr/bin/env python3
"""
Deterministic Postgres/ORM migration validator for Claude Code Skill.
Exits with 0 on pass, 1 on critical safety violation.
"""
import argparse
import json
import re
import sys

HAZARDS = [
    (r"ALTER\s+TABLE\s+\w+\s+ADD\s+COLUMN\s+\w+.*NOT\s+NULL", "ACCESS EXCLUSIVE table rewrite lock"),
    (r"CREATE\s+INDEX\s+(?!CONCURRENTLY)", "Index created without CONCURRENTLY locks table writes"),
    (r"DROP\s+TABLE\s+", "Destructive table deletion without archival step"),
    (r"RENAME\s+COLUMN\s+", "Breaking column rename breaks in-flight application queries"),
]

def check_migration(filepath: str, level: str):
    violations = []
    with open(filepath, "r", encoding="utf-8") as f:
        content = f.read()

    for pattern, warning in HAZARDS:
        matches = re.finditer(pattern, content, re.IGNORECASE)
        for m in matches:
            line_no = content[:m.start()].count("\n") + 1
            violations.append({"line": line_no, "hazard": warning, "snippet": m.group(0)})

    result = {
        "file": filepath,
        "violations": violations,
        "status": "FAILED" if (violations and level == "strict") else "PASSED"
    }

    print(json.dumps(result, indent=2))
    if violations and level == "strict":
        sys.exit(1)
    sys.exit(0)

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--file", required=True)
    parser.add_argument("--level", default="strict")
    args = parser.parse_args()
    check_migration(args.file, args.level)

5. Advanced Subagent Orchestration within Skills

One of Claude Code's most powerful capabilities is subagent delegation. When a skill requires broad codebase scanning, analyzing dependencies, or testing multiple hypotheses, keeping everything in the primary agent thread quickly consumes 100k+ tokens.

Preventing Context Explosion with Subagents

By declaring subagent delegates inside your skill definition, Claude Code spawns isolated worker agents. The subagent operates with its own clean scratchpad, performs its investigation, and returns only a compressed, typed JSON summary back to the parent orchestrator:

Subagent Delegation Pattern:
+-------------------------------------------------------------------------+
| Primary Agent Thread (Clean, 14k tokens)                                |
| > /security-audit                                                      |
+-------------------------------------------------------------------------+
       |
       | 1. Spawn Worker (Clean Context Window: 0 tokens)
       v
+-------------------------------------------------------------------------+
| Subagent: "SecurityScanner" (Consumes 180k tokens analyzing 42 files)    |
| - Runs AST grep, parses dependencies, evaluates taint graph             |
| - Generates structured JSON findings                                    |
+-------------------------------------------------------------------------+
       |
       | 2. Return Compressed Summary Only (~1.2k tokens)
       v
+-------------------------------------------------------------------------+
| Primary Agent Thread (Now 15.2k tokens)                                 |
| - Reviews 3 identified vulnerabilities                                  |
| - Generates targeted patch files without context dilution               |
+-------------------------------------------------------------------------+

Implementing Subagent Invocations in `SKILL.md`

To instruct Claude Code to delegate tasks to a subagent, use the subagent directive inside SKILL.md:

---
name: multi-service-refactor
description: Coordinates cross-package architectural refactoring across monorepo microservices.
subagent_delegation:
  max_parallel_workers: 4
  worker_model: "claude-3-7-sonnet"
---

# Cross-Service Refactoring Protocol

When coordinating changes across `/packages/auth`, `/packages/api`, and `/packages/gateway`:

1. **Parallel Analysis Phase**:
   Spawn independent read-only subagents for each package:
   - Worker 1: Trace symbol consumers in `/packages/auth`.
   - Worker 2: Trace route handlers in `/packages/api`.
   - Worker 3: Verify gateway proxy contracts in `/packages/gateway`.

2. **Reconciliation Barrier**:
   Each subagent must yield an interface artifact:
   ```json
   {
     "package": "packages/auth",
     "breaking_changes": ["SessionManager.revokeToken() signature changed"],
     "required_callsite_updates": 12
   }
   ```

3. **Sequential Mutation**:
   The primary agent executes file writes sequentially, verifying typecheck across the monorepo after each package update.

6. Top 10 Recommended Production Claude Code Skills for 2026

Below are the 10 most valuable open-source and enterprise skills widely adopted by high-velocity software engineering teams in 2026:

Top 10 Claude Code Skills Ecosystem:
┌──────────────────────────────────────┬──────────────────────────────────────┐
│ Skill Name                           │ Core Functionality                   │
├──────────────────────────────────────┼──────────────────────────────────────┤
│ 1. pr-security-auditor               │ AST taint analysis & secret scanner  │
│ 2. git-atomic-committer              │ Conventional commits + git bisect    │
│ 3. db-migration-guard                │ Zero-downtime Postgres & ORM safety  │
│ 4. playwright-e2e-verifier           │ Headless browser visual regression   │
│ 5. openapi-contract-sync             │ Swagger/OpenAPI schema validator     │
│ 6. ast-grep-codemod                  │ Structural multi-file AST refactoring│
│ 7. docker-rootless-linter            │ Container security & layer optimizer │
│ 8. prompt-cache-profiler             │ Token economics & KV-cache analytics │
│ 9. jetbrains-symbol-bridge           │ IDE PSI index search accelerator     │
│ 10. pnpm-turborepo-orchestrator      │ Monorepo dependency drift cleaner    │
└──────────────────────────────────────┴──────────────────────────────────────┘

1. `pr-security-auditor`

Location: .claude/skills/pr-security-auditor/
Purpose: Runs static taint analysis on staged git diffs before pull request creation. Scans for hardcoded credentials, SQL injection vectors, and prototype pollution in JavaScript/TypeScript and Python.

2. `git-atomic-committer`

Location: .claude/skills/git-atomic-committer/
Purpose: Groups large multi-file refactoring sessions into clean, bisect-friendly atomic git commits adhering to Conventional Commits standards. Validates that every intermediate commit successfully builds and passes unit tests.

3. `db-migration-guard`

Location: .claude/skills/db-migration-guard/
Purpose: Evaluates proposed Prisma, Drizzle, Alembic, or raw SQL migrations against Postgres locking matrix rules to prevent production database outages.

4. `playwright-e2e-verifier`

Location: .claude/skills/playwright-e2e-verifier/
Purpose: Automatically generates and executes headless Playwright end-to-end browser tests to visually verify frontend layout changes before committing.

5. `openapi-contract-sync`

Location: .claude/skills/openapi-contract-sync/
Purpose: Compares backend route handler implementations against public OpenAPI/Swagger specifications, catching undocumented API drift and typing mismatches.

6. `ast-grep-codemod`

Location: .claude/skills/ast-grep-codemod/
Purpose: Leverages ast-grep (sg) to perform syntax-tree-accurate replacements across hundreds of files, avoiding the fragile edge cases of regex find-and-replace.

7. `docker-rootless-linter`

Location: .claude/skills/docker-rootless-linter/
Purpose: Enforces non-root user execution, multi-stage build minimization, and vulnerability scanning (trivy/grype) across Dockerfiles and Compose configurations.

8. `prompt-cache-profiler`

Location: .claude/skills/prompt-cache-profiler/
Purpose: Inspects active Claude Code sessions, calculating token cache hit ratios, identifying cache-busting dynamic variables, and recommending token budget optimizations.

9. `jetbrains-symbol-bridge`

Location: .claude/skills/jetbrains-symbol-bridge/
Purpose: Interfaces with the JetBrains IDE socket bridge, pulling symbol hierarchy data directly from IntelliJ's compilation index into Claude Code.

10. `pnpm-turborepo-orchestrator`

Location: .claude/skills/pnpm-turborepo-orchestrator/
Purpose: Manages monorepo topological build graphs, validating that package dependencies, exports maps, and workspace protocols remain synchronized.

7. Token Economics, Prompt Caching & Security Governance

Preserving 90% Prompt Caching Discounts

Anthropic's prompt caching provides a 90% discount on input tokens when prompt prefixes remain identical across turns. Monolithic configuration strategies constantly invalidate this cache:

Monolithic vs. Modular Skills Caching Mechanics:

A) Monolithic CLAUDE.md:
Turn 1: [Prefix: 12,000 tokens (CLAUDE.md)] ──> Cache Write (Full Price)
Turn 2: [User edits 1 line in CLAUDE.md] ─────> CACHE MISS! Re-index 12,000 tokens ($$$)

B) Modular .claude/skills/:
Turn 1: [Stable Base Prefix: 2,500 tokens] ────> Cache Read (90% Discount)
Turn 2: [/db-migration called] ───────────────> Ingests 1,200 tokens (Appended at tail)
                                               Base prefix remains 100% CACHE HIT!

By keeping base project instructions minimal and appending skills dynamically only when invoked, teams achieve steady 92% to 96% cache hit ratios, dropping average PR resolution costs from $2.40 down to $1.25.

Security Sandbox: Permissions & Defense-in-Depth

Skills can execute arbitrary shell scripts. To prevent supply chain poisoning or malicious prompts injected via external pull requests, configure granular permission controls in .claude/permissions.json:

{
  "permissions": {
    "allow_shell_commands": [
      "git status",
      "git diff",
      "pnpm test *",
      "python3 .claude/skills/*"
    ],
    "deny_shell_commands": [
      "rm -rf /",
      "curl * | bash",
      "sudo *"
    ],
    "require_human_confirmation": [
      "git push *",
      "npm publish",
      "docker run *"
    ]
  },
  "skill_isolation": {
    "network_access": "restricted",
    "timeout_seconds": 60
  }
}

Never execute third-party skills with the --dangerously-skip-permissions flag on bare-metal developer machines. Run automated CI skill loops inside isolated Docker containers or ephemeral microVMs (e.g., Firecracker or Fly Machines).

8. Strategic Roadmap: Adopting Skills in Your Engineering Team

To scale AI engineering productivity across your organization, follow this four-phase implementation roadmap:

Implementation Timeline:
Week 1: Audit & Cleanse ──> Week 2: IDE Plugin Rollout ──> Week 3: First 3 Skills ──> Week 4: Subagents & CI
  • Deprecate CLAUDE.md     • Install JetBrains/VSCode     • PR Auditor               • Cross-service tasks
  • Measure Token Waste     • Establish Hotkey Muscle      • DB Migration Guard       • Continuous Benchmarks

Phase 1: Audit & Deprecate Monoliths: Audit your existing CLAUDE.md or .cursorrules. Remove code snippets, database schemas, and tool-specific runbooks. Strip the file down to pure architectural guidelines under 100 lines.
Phase 2: Standardize IDE Bridges: Deploy the official Claude Code JetBrains and VS Code plugins across the development team. Establish standard keyboard shortcuts and teach engineers to utilize gutter diffs.
Phase 3: Deploy Core Safety Skills: Implement .claude/skills/pr-security-auditor and .claude/skills/db-migration-guard. Enforce deterministic Python validation scripts to establish guardrails on automated refactorings.
Phase 4: Leverage Subagent Orchestration: For monorepos and cross-service repositories, introduce subagent delegation skills to handle multi-file migrations without context window degradation.

By transitioning from monolithic prompts to modular skills, subagents, and IDE integrations, engineering teams unlock the true potential of autonomous coding agents in 2026: achieving higher benchmark resolve rates, robust safety guarantees, and predictable token economics.

Claude Code Skills & Plugins Guide: Architecture & Setup

1. The Architectural Shift: Moving Beyond Monolithic CLAUDE.md

The Modern Extension Triumvirate

2. Quantitative Matrix: Skills vs. MCP vs. Subagents vs. Hooks

Impact on Benchmark Performance & Costs

3. JetBrains IDE Integration: IntelliJ, WebStorm, and PyCharm

Key Plugin Capabilities

Installation & Configuration Guide

4. Deep-Dive: Building Custom .claude/skills/ with Schema Validation

Anatomy of SKILL.md

Creating the Deterministic Helper Script

5. Advanced Subagent Orchestration within Skills

Preventing Context Explosion with Subagents

Implementing Subagent Invocations in SKILL.md

6. Top 10 Recommended Production Claude Code Skills for 2026

1. pr-security-auditor

2. git-atomic-committer

3. db-migration-guard

4. playwright-e2e-verifier

5. openapi-contract-sync

6. ast-grep-codemod

7. docker-rootless-linter

8. prompt-cache-profiler

9. jetbrains-symbol-bridge

10. pnpm-turborepo-orchestrator