The Complete Guide to Claude Skills, Plugins, and Rules

Every Claude Code session begins the same way: the agent reads its context, picks its tools, and starts building. But what determines whether it builds correctly—whether it follows your team's conventions, uses the right frameworks, and avoids costly mistakes—has nothing to do with the prompt you type.

It depends on the harness you've configured around it.

This guide covers every component of the Claude Code harness: skills, rules files, MCP servers, hooks, sub-agents, and plugins. You'll learn how each mechanism works, when to use it, and how to combine them into a system that makes your coding agent reliably effective. Whether you're setting up your first CLAUDE.md or designing a multi-skill architecture for a team, this guide gives you the practical knowledge to do it right.

What Is Harness Engineering for Claude Code

Harness engineering is the practice of configuring the environment, rules, and tools around a coding agent to improve its reliability. The term, coined by the team at HumanLayer, defines the agent as:

coding agent = AI model(s) + harness

The harness is everything the model uses to interact with its environment—the configuration surface that shapes what the agent knows, what it can do, and how it verifies its work. This is distinct from prompt engineering. While prompt engineering focuses on what you say to the agent, harness engineering focuses on the system that wraps the agent.

The key components of the Claude Code harness include:

• Rules files (CLAUDE.md, .claude/rules/): persistent instructions loaded every session

• Skills: reusable instruction sets that activate on demand

• MCP servers: connections to external tools and APIs

• Hooks: deterministic scripts triggered at lifecycle events

• Sub-agents: isolated Claude instances for delegated subtasks

The core principle of harness engineering is: anytime the agent makes a mistake, engineer a solution so it never makes that mistake again. Over time, your harness accumulates institutional knowledge that makes the agent progressively more reliable.

Harness Engineering as a Subset of Context Engineering

Context engineering is the broader discipline of shaping what information an agent receives. Anthropic's own guidance on context engineering frames it as treating the context window like a finite resource with an "attention budget"—every token added depletes the model's ability to focus on what matters.

Harness engineering is the structural subset of context engineering. It focuses on the mechanisms—files, configs, tools, and lifecycle hooks—rather than conversational prompts. The diagram below illustrates this relationship:

Figure: Context engineering encompasses both harness engineering (structural) and prompt engineering (conversational).

Why Harness Architecture Matters for Agent Reliability

Without a proper harness setup, agents exhibit predictable failure modes:

• Context rot: Performance degrades during long sessions as stale information fills the context window.

• Inconsistent decisions: Without rules, the agent makes different choices in identical situations across sessions.

• Tool confusion: Too many tools with overlapping functionality degrade the agent's decision-making quality.

• Knowledge gaps: The agent doesn't know your team's conventions, framework patterns, or forbidden actions unless you teach it.

Each of these failure modes has a structural solution covered later in this guide. The harness is your lever to fix them systematically.

How Claude Code Skills Extend Agent Capabilities

Skills are reusable instruction sets stored as directories with a SKILL.md file that Claude Code can invoke when triggered. They teach Claude domain-specific behaviors without cluttering the main rules file.

• What skills contain: A SKILL.md file with instructions, optional supporting files (templates, scripts, reference docs), and YAML frontmatter metadata.

• Where skills live: In project directories (.claude/skills/), user home folders (~/.claude/skills/), installed plugins, or enterprise-managed locations.

• When skills activate: Based on Claude's assessment of task relevance (via the skill's description), explicit user invocation (/skill-name), or by being set to always load.

Skills solve the progressive disclosure problem. Instead of stuffing every possible instruction into the system prompt, skill descriptions are loaded at session start, but the full SKILL.md content is only loaded into context when Claude determines the skill is relevant. This conserves the context window for what actually matters.

Skill File Structure and the SKILL.md Format

A skill is a directory with a SKILL.md file as its entrypoint. The SKILL.md consists of YAML frontmatter (containing metadata) followed by markdown instructions.

Here's an example SKILL.md for a React component skill:

Key frontmatter fields include:

Note: You may see references to .mdc files in some community resources. This is the older Cursor Rules format. Claude Code's official skill format uses SKILL.md files as defined in the Agent Skills open standard.

Bundled Skills vs Custom Skills

Claude Code's plugin ecosystem provides pre-built skills, while custom skills address project-specific needs.

Community repositories like alirezarezvani/claude-skills offer 205+ production-ready skills across nine domains, from engineering to marketing. These can serve as starting points for your own custom skills.

Progressive Disclosure in Skill Design

Well-designed skills follow Anthropic's progressive disclosure best practices: they reveal information incrementally rather than loading everything at once.

The pattern works like this:

Figure: Skills load incrementally. Descriptions are always available; full instructions load on demand; reference files load only when needed.

Anthropic recommends keeping SKILL.md under 500 lines. Move detailed reference material into separate files and reference them from SKILL.md. This ensures zero context tokens are consumed by supporting files until Claude actually needs them.

How to Write Effective CLAUDE.md Rules Files

The CLAUDE.md file is the primary rules file that configures Claude Code's behavior within a project. It loads at the start of every session as a user message after the system prompt. Think of it as the agent's onboarding document—the same information you'd give a new team member on their first day.

According to Anthropic's own documentation, effective rules are concise, actionable instructions rather than verbose documentation. The target is under 200 lines per file.

What to Include in Your CLAUDE.md

Your CLAUDE.md file should include these essential sections:

• Project context: A 1-2 line description of what the codebase does and its architecture.

• Build and test commands: How to run tests, linters, and build scripts (npm run test, pytest -x, etc.).

• Code style preferences: Non-default conventions only—formatting, naming conventions, file organization.

• Forbidden actions: A list of what the agent should never do (e.g., "Never modify migration files directly").

• Domain-specific terminology: Definitions of terms and concepts specific to your project.

• Directory structure overview: Where key files live and the organizational pattern.

Here's a stripped-down example:

Notice the @ imports at the bottom—Claude Code supports importing additional files to keep the main CLAUDE.md lean while providing access to detailed documentation when needed.

For modular organization, use .claude/rules/*.md files to split instructions by topic:

Rules files without paths frontmatter load at launch alongside CLAUDE.md. Path-specific rules only load when Claude works with matching files—another form of progressive disclosure.

Team Configuration with Rules and .dinorules

Teams can enforce consistent agent behavior across repositories using shared configuration files. The CLAUDE.md and .claude/rules/ directory should be version-controlled so every developer gets the same agent behavior.

For data teams working with dbt™, Paradime's Code IDE supports team-wide configuration via .dinorules and .dinoprompts. These serve a similar purpose to CLAUDE.md but are specialized for analytics engineering workflows:

• .dinorules: Codify SQL formatting standards, naming conventions (like stg_, int_, dim_, fct_ prefixes), folder structure, documentation requirements, and business logic patterns. DinoAI analyzes your existing project files to auto-generate rules that match your established patterns.

• .dinoprompts: A YAML-based prompt library where teams store and share reusable prompts for common data workflows—generating documentation, writing tests, creating staging models.

Both files are git-tracked by default, meaning any developer on the team gets the same AI-assisted experience from day one.

MCP Servers vs Skills vs Hooks vs Sub-Agents

Claude Code provides four primary extension mechanisms, each solving a different problem. Choosing the right one is critical.

Figure: The four extension mechanisms plug into different parts of the Claude Code agentic loop.

MCP Servers for External Tool Integration

MCP (Model Context Protocol) servers provide Claude Code with access to external tools like databases, APIs, and file systems. They're the bridge between the agent and the outside world.

Configuring an MCP server is straightforward:

MCP servers can be scoped to local (your machine, this project), project (version-controlled in .mcp.json), or user (all your projects) levels. The /mcp command lists all configured servers.

For data teams, Paradime's Code IDE connects to 30+ tools via MCP through a single unified interface—including Snowflake, BigQuery, Databricks, GitHub, Jira, and Notion—without requiring manual server configuration.

Important performance note: When the total token count of MCP tool definitions exceeds 10% of the context window, Claude Code automatically enables MCP Tool Search. Instead of loading all tool definitions upfront, Claude uses a search tool to discover relevant tools on demand. This prevents tool overload from consuming your context budget.

Skills for Reusable Domain Knowledge

Unlike MCP servers, which provide live tool connections, skills contain instructions and patterns. Use skills to teach Claude how to approach specific frameworks, adhere to coding standards, or work within a particular codebase.

The key difference: MCP servers answer "what can I connect to?" while skills answer "how should I approach this?"

For example, you wouldn't use an MCP server to teach Claude your dbt™ naming conventions. That's a skill:

And here's one that blocks edits to protected files:

Exit code 2 blocks the tool call, and the stderr message is fed back to Claude as context.

Sub-Agents for Context Isolation and Cost Control

Sub-agents are separate Claude instances that handle subtasks without polluting the main agent's context. They act as a context firewall: the parent agent only sees the prompt it sent and the summarized result—none of the intermediate tool calls, file reads, or reasoning.

This provides two critical benefits:

1. Prevents context rot: Long sessions accumulate stale information. Sub-agents keep the main context clean by handling research-heavy or exploration tasks in isolation.

2. Reduces token costs: Since results are summarized back, the main agent consumes far fewer tokens than if it had done the work inline.

You can invoke sub-agents through skills using the context: fork frontmatter:

When this skill activates, it runs in an isolated context. The main agent receives only the summary, keeping its context window lean.

How to Create and Structure Claude Code Skills

Follow these steps to create your first skill.

1. Define Skill Metadata and Triggers

Create a skill directory with a SKILL.md file. In the frontmatter, define the skill's metadata. The description is the most critical field—Claude uses it to decide when to apply the skill from potentially hundreds of available options.

Anthropic's best practices recommend writing descriptions in third person that include both what the skill does and when to use it. Avoid vague descriptions like "Helps with testing"—be specific about the triggers.

2. Write Clear Skill Instructions

Write instructions as concrete, actionable guidance. Keep the SKILL.md body under 500 lines and move detailed reference material to supporting files.

3. Include Supporting Files When Needed

Skills can bundle templates, scripts, and reference documentation. Only add supporting files when the skill requires them—keep the structure minimal.

Reference these files from SKILL.md with clear descriptions so Claude knows what they contain and when to load them.

4. Test Skill Activation in Your Workflow

Verify that your skill loads correctly:

1. Invoke explicitly: Type /pytest-patterns to manually trigger the skill.

2. Check automatic activation: Create a test file and observe whether Claude references the skill's instructions.

3. Review the skill list: Use /skills to see all available skills and their descriptions.

4. Iterate with real usage: Anthropic recommends testing skills with real tasks across multiple model versions (Haiku, Sonnet, Opus) to ensure consistent behavior.

Figure: Iterative skill development workflow—create, test, refine, deploy.

Common Claude Code Setup Mistakes and How to Fix Them

Here are practical solutions to problems developers frequently encounter.

Rules Not Loading from Plugin Installations

• Problem: You've installed a plugin like Everything Claude Code, but expected behaviors aren't appearing.

• Why it happens: Plugin rules, skills, and hooks are namespaced and scoped. They don't automatically merge into your project's CLAUDE.md. Some plugin components (like hooks) activate automatically, but behavioral rules in the plugin's own CLAUDE.md only apply to that plugin's context.

• Solution: Review the plugin's contents and selectively copy relevant rules into your project's CLAUDE.md or .claude/rules/ directory. Use /skills and /hooks to verify what's actually active.

Tool Overload Degrading Agent Performance

• Problem: The agent is confused or performing poorly after you've added many MCP servers or tool-heavy skills.

• Why it happens: Anthropic's research confirms this is one of the most common failure modes. If a human engineer can't definitively say which tool should be used for a given task, the AI agent can't either. Tool definitions consume context tokens, and overlapping functionality creates ambiguous decision points.

• Solution: Curate a minimal viable set of tools. Only enable MCP servers necessary for the current task. Use the ENABLE_TOOL_SEARCH environment variable to let Claude discover tools on demand rather than loading them all upfront. Set ENABLE_TOOL_SEARCH=auto:5 to activate tool search when tools exceed 5% of context.

Context Rot in Extended Sessions

• Problem: The agent's performance degrades noticeably during long sessions—it starts forgetting earlier instructions, makes inconsistent choices, or hallucinates.

• Why it happens: As tokens accumulate in the context window, the model's ability to accurately recall earlier information decreases. Research from Chroma demonstrates this degradation empirically.

• Solution: Use sub-agents for discrete subtasks. Use /compact to compress the conversation. Start a fresh session (/clear) when switching to a new complex task. Design hooks to surface errors silently—success should be quiet; only failures should produce verbose output.

How to Activate Claude Code Skills Reliably

Skills may not always trigger when you expect them to. Here's how to ensure consistent activation.

Keyword and Pattern-Based Skill Triggering

Claude decides which skills to activate based on two signals:

1. Description matching: Claude reads all skill descriptions at session start and chooses relevant ones based on the current task. A description like "Writes Python unit tests with pytest" will activate when Claude detects it's working on Python tests.

2. Explicit invocation: Users can type /skill-name to manually trigger any skill.

To improve automatic activation:

• Write descriptions with specific keywords that match how tasks are naturally described.

• Include both what the skill does and when to use it in the description.

• Avoid descriptions that overlap with other skills' domains.

• If a skill should only be manually invoked (like a deployment checklist), set disable-model-invocation: true.

Measuring Activation with Sandboxed Evals

Anthropic's skill authoring best practices recommend an iterative development approach:

1. Build evaluations first: Create at least three test scenarios before writing the skill.

2. Use two Claude instances: Work with Claude A to create and refine the skill, then test with Claude B on real tasks.

3. Observe navigation patterns: Watch how Claude navigates the skill's supporting files. Look for unexpected exploration paths, missed connections, or ignored content.

4. Test across models: Verify the skill works with Haiku, Sonnet, and Opus since each model may interpret instructions differently.

When to Use Skills vs MCP Servers vs Sub-Agents

Use this decision framework:

• Need to connect to an external API or database? → Use an MCP server

• Need to teach Claude a framework or coding pattern? → Use a skill

• Need to isolate a risky or long-running task? → Use a sub-agent

• Need to automate actions before/after tasks? → Use a hook

Figure: Decision tree for choosing the right Claude Code extension mechanism.

Skills for Domain-Specific Knowledge

Use skills for encoding knowledge like dbt™ model conventions, company-wide coding standards, or framework-specific patterns. Skills are the right choice when the information is:

• Reusable across multiple sessions and tasks

• Domain-specific to your project or framework

• Too detailed for CLAUDE.md but too important to leave out

• Conditionally needed rather than always relevant

MCP Servers for API and Tool Access

Use MCP servers for actions requiring external access: running Snowflake queries, creating Jira tickets, performing GitHub operations, or querying Sentry for errors. The key characteristic is that MCP servers provide live, bidirectional connections to external services.

Paradime's Code IDE takes this further with MCP integrations spanning data warehouses (Snowflake, BigQuery, Databricks, Redshift), version control (GitHub, GitLab, Azure Repos), ticketing (Jira, Linear, Asana), and documentation tools (Notion, Confluence)—all connected through a single interface.

Sub-Agents for Long-Running or Isolated Tasks

Use sub-agents for tasks like:

• Codebase research: Reading many files but returning only key findings

• Module refactoring: Making extensive changes in isolation before summarizing results

• Test suite investigation: Running and analyzing tests without flooding main context

• Parallel workstreams: Multiple sub-agents can work simultaneously on independent tasks

The sub-agent receives a fresh context containing the system prompt, specified skills, CLAUDE.md, git status, and whatever the lead agent passes—but not the conversation history or previously invoked skills.

How to Organize Skills Across Projects and Teams

As teams adopt Claude Code, these strategies help manage and scale skill usage.

Plugin Marketplaces and Skill Repositories

An ecosystem of shareable skills and plugins is rapidly growing. Key resources include:

• Everything Claude Code (ECC): Over 100K GitHub stars. Bundles 125 skills, 28 agents, 60 commands, 34 rules, and 14 MCP server configurations. Supports Claude Code, Cursor, Codex CLI, and OpenCode.

• alirezarezvani/claude-skills: 205 production-ready skills across 9 domains with 268 Python CLI tools.

• Claude Marketplaces: A curated directory of plugins, skills, and MCP servers.

• Official Anthropic marketplace: Available via /plugin marketplace add anthropics/claude-code in the CLI.

To install a plugin:

Enforcing Team Standards with Shared Configuration

Teams can ensure consistency by:

1. Version-controlling .claude/: Commit your CLAUDE.md, .claude/rules/, .claude/skills/, and .claude/settings.json to the repository.

2. Project-scoped plugins: Install plugins with --scope project so the settings appear in .claude/settings.json and are shared via git.

3. Managed policies: For enterprise teams, use managed settings at the OS level to enforce organization-wide rules.

For data teams, Paradime enables team-wide AI configuration with .dinorules and .dinoprompts—both git-tracked by default—to standardize AI behavior across all dbt™ projects without relying on each developer to maintain their own setup.

The Claude Code Plugin and Skill Ecosystem

Everything Claude Code and Popular Community Plugins

Everything Claude Code (ECC) is the most widely adopted extension, bundles a comprehensive system of skills, agents, commands, rules, and hooks evolved over months of intensive daily use. Its structure demonstrates key harness engineering principles:

• Skills: 125 specialized instruction sets organized by domain

• Agents: 28 pre-configured agent definitions for specific roles

• Hooks: Lifecycle automation for formatting, testing, and notifications

• MCP configurations: 14 pre-built server setups for common services

After installation, review which components are active using /skills, /hooks, and /mcp. Selectively integrate rules from the plugin's documentation into your project's CLAUDE.md to activate the specific behaviors you need.

Framework and Domain-Specific Skill Kits

The community has built skill kits for virtually every domain:

• Frontend: React, Svelte, Vue, Next.js component patterns

• Backend: Python/FastAPI, Node/Express, Go service patterns

• Data: SQL, dbt™, data pipeline conventions

• Testing: pytest, vitest, Playwright, Jest patterns

• DevOps: Docker, Terraform, CI/CD workflows

These kits can be adapted for specialized workflows. For example, a dbt™ skill kit can encode your team's specific model naming conventions, materialization strategies, and testing requirements—knowledge that's otherwise lost in onboarding documents.

Context Engineering Best Practices for Coding Agents

These strategic principles, drawn from Anthropic's guidance and practitioner experience, make harnesses more effective.

Keep Your Tool Count Manageable

Anthropic is explicit on this point: bloated tool sets are one of the most common failure modes for AI agents. Every tool definition consumes context tokens, and overlapping tools create ambiguous decision points.

Practical guidelines:

• Audit your MCP servers regularly. Disable any that aren't needed for the current project phase.

• Use ENABLE_TOOL_SEARCH=auto to defer tool loading until needed.

• Ensure tools have no overlap in functionality and are self-contained with clear descriptions.

• If you can't tell which of two tools should handle a task, neither can the agent.

Use Sub-Agents to Prevent Context Rot

Offload research, exploration, and discrete subtasks to sub-agents. This keeps the main context window clean and focused, which is especially important during long or complex sessions.

The pattern is simple: instead of asking the main agent to "look through all the test files and figure out our patterns," delegate that to a sub-agent. The main agent gets a concise summary, not thousands of lines of file contents.

Apply Back-Pressure for Higher Success Rates

Back-pressure is the practice of constraining an agent's scope to improve its reliability. Verification mechanisms—typechecks, tests, linters—act as back-pressure that tells the agent when something is wrong.

Key principles from the HumanLayer team's experience:

• Success should be silent: Only surface errors in hook output. Running the full test suite and showing 4,000 lines of passing tests floods the context and causes the agent to lose focus.

• Run subsets, not full suites: A targeted test run after each change is more effective than a 5-minute full suite run.

• Smaller tasks succeed more: Well-scoped, single-responsibility tasks have dramatically higher completion rates than ambitious multi-step prompts.

Why Data Teams Choose AI-Native Development Platforms

The principles of harness engineering—structured context, integrated tools, and reusable configurations—are directly applicable to data engineering workflows. When you're writing dbt™ models, you need the agent to understand your warehouse schema, your naming conventions, your materialization strategy, and your testing requirements.

Paradime's Code IDE is an AI-native environment built on these exact principles. Where Claude Code users must manually configure MCP servers for warehouse access and write custom skills for dbt™ patterns, Paradime provides this out of the box:

• Warehouse-aware assistance: DinoAI has native context about your Snowflake, BigQuery, Databricks, or Redshift schemas—tables, columns, and relationships are available without configuring MCP servers.

• Column-level lineage: Visual lineage between dbt™ models and downstream dashboards, built into the IDE.

• Team-wide standards via .dinorules: Codify your SQL formatting, naming conventions, and documentation patterns once. Every developer's AI assistant follows them automatically.

• Reusable prompt library via .dinoprompts: Store proven prompts for common workflows—generating staging models, adding documentation, writing tests—so the team never starts from scratch.

• 30+ MCP integrations: Connect to your entire tech stack through a single interface with zero configuration.

Start for free →

FAQs About Claude Code Skills and Harness Engineering

How do Claude Code skills apply to dbt™ and data engineering workflows?

Skills can encode dbt™ best practices, SQL patterns, and warehouse-specific conventions—like model naming (stg_, int_, fct_, dim_), materialization rules, and required YAML documentation. This is conceptually similar to how Paradime's DinoAI uses .dinorules and .dinoprompts to provide warehouse-aware assistance. The difference is that Paradime provides this configuration natively for analytics engineers, while Claude Code requires manual skill authoring.

Can Claude Code skills integrate with Snowflake and BigQuery data warehouses?

Warehouse connectivity is handled by MCP servers, not skills directly. Skills teach Claude how to write queries and use warehouse features (e.g., Snowflake-specific SQL syntax), while MCP servers provide the live connection needed to fetch metadata, preview data, and execute queries. You need both: an MCP server for access and a skill for conventions.

What happens when too many Claude Code skills are active simultaneously?

Activating too many skills fills the context window and can confuse the agent's decision-making. To mitigate this:

• Write specific, non-overlapping skill descriptions so Claude only loads what's relevant.

• Use disable-model-invocation: true for skills that should only be manually triggered.

• Keep SKILL.md files under 500 lines with supporting details in separate files.

• Use the context: fork option to run context-heavy skills in isolated sub-agents.

How can teams enforce consistent Claude Code skill usage across developers?

Version-control your .claude/ directory, including CLAUDE.md, rules/, skills/, and settings.json. Install team plugins with --scope project so they're tracked in the project settings. For enterprise teams, use managed settings at the OS level. Data teams using Paradime can standardize AI behavior with .dinorules and .dinoprompts, which are git-tracked and shared automatically.

Are Claude Code skills compatible with Cursor and other AI coding assistants?

Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools including Codex, OpenCode, and others that support the standard. Cursor uses its own .cursor/rules/ configuration format. While the high-level principles of context engineering (progressive disclosure, structured instructions, minimal tool sets) are transferable, the specific file formats differ between platforms.

What is the difference between CLAUDE.md rules and .dinorules files?

CLAUDE.md is the configuration file for the general-purpose Claude Code agent. It covers everything: coding standards, build commands, architecture context, and domain-specific instructions. .dinorules is Paradime's configuration format for its DinoAI assistant, specialized for dbt™ and data workflows. It focuses on SQL formatting, model naming conventions, documentation requirements, and business logic patterns. Both serve the same purpose—customizing AI assistant behavior—but .dinorules is purpose-built for analytics engineering with auto-generation from existing project patterns.