Claude Code v2.1.157: Drop a SKILL.md and It Just Works (No Marketplace Required)

Claude Code v2.1.157 (released May 29, 2026) automatically loads skills and plugins from .claude/skills/ directories on session start - no marketplace, no --plugin-dir flag, no manual install. Drop a folder containing a SKILL.md file into .claude/skills/, start a new session, and Claude picks it up. The update also added claude plugin init <name> for scaffolding and autocomplete for /plugin arguments.

Claude Code shipped v2.1.157 on May 29 and buried one of its most useful features in the changelog: skills and plugins in .claude/skills/ directories are now automatically loaded. No marketplace. No --plugin-dir flag on every launch. No configuration. Drop a file and it works.

Most builders will scroll past this in the release notes. That would be a mistake. This is the closest Claude Code has come to making persistent, project-specific behavior feel native rather than bolted on.

If you've been re-explaining your folder structure, naming conventions, or deployment process to Claude at the start of every session, this update ends that.

What Changed in Claude Code v2.1.157?

Three things shipped that make the skills system significantly more usable.

1. Auto-loading from .claude/skills/. Before v2.1.157, using a local plugin required either publishing to a marketplace or passing --plugin-dir on every launch. Both added friction. Most builders skipped it entirely. Now, Claude Code scans .claude/skills/ on session start and loads whatever valid skills or plugins it finds. No flags, no install step.

This works at two levels:

Scope	Path	Behavior
Project	.claude/skills/ in your repo	Loads only in that project. Commit to git and every teammate gets it.
Personal	~/.claude/skills/ in home dir	Loads across every project on your machine.

Skills also walk up parent directories to the repository root, so starting Claude from a subdirectory still picks up skills defined at the project root.

2. claude plugin init <name> scaffolding. Run the command, get a working plugin skeleton in .claude/skills/. No boilerplate. Supports --with skills,agents,hooks,mcp flags to scaffold specific components.

3. Autocomplete for /plugin arguments. Subcommands, installed plugin names, and plugins from known marketplaces all appear as you type.

Why Does Auto-Loading Skills Matter for Builders?

Here's what the problem actually looks like in practice.

You open a new Claude session on your backend repo. You type: "hey, we use snake_case for functions, tests go in /tests mirroring /src, and never modify the database schema directly - always write a migration." Claude nods. You ship something. You open a new session the next day. You type the same paragraph again.

Over a month, that's hundreds of tokens and minutes of re-orientation per session. Worse, Claude occasionally drifts from conventions mid-session when context grows long, because the instructions were only in the conversation, not grounded in the project.

Skills loaded from .claude/skills/ solve this in three ways:

1. They're grounded. Part of the project, not part of the chat. They reload every session automatically.
2. They're on-demand. Unlike CLAUDE.md (which loads every turn), skills use progressive disclosure. Claude sees the skill name and description (~100 tokens), but only loads the full instructions (~5K tokens) when the task matches. That saves context for the work that matters.
3. They're version-controlled. Commit .claude/skills/ to your repo. Every team member gets identical Claude behavior without any individual setup. New engineers onboard to a Claude that already knows the project.

How Do You Set Up Auto-Loaded Skills? (Under 5 Minutes)

The simple way - just a SKILL.md:

You don't need a full plugin structure. A folder with a single SKILL.md file works:

mkdir -p .claude/skills/project-conventions

Create .claude/skills/project-conventions/SKILL.md:

---
name: Project Conventions
description: Use when writing or reviewing code in this project. Covers naming, testing, and database rules.
---

## Code Style
Use snake_case for Python functions. Always add type hints.
Keep functions under 50 lines - split if longer.

## Testing
Write tests in pytest. Mirror /src structure under /tests.
Every new function needs at least one test.

## Database
Never modify schema directly. Always write an Alembic migration.
Migration files go in /migrations with a descriptive name.

PR Reviews

When reviewing PRs: check type hints, function length, test coverage, and confirm no direct schema modifications.

That's it. Next Claude Code session, this skill loads automatically. Claude invokes it when the task matches the description in the frontmatter.

The full plugin way - with claude plugin init:

For more complex setups that need agents, hooks, or MCP servers alongside skills:

claude plugin init my-project-tools --with skills,hooks

This scaffolds a complete plugin structure:

.claude/skills/my-project-tools/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata (name, version, description)
├── skills/
│   └── my-project-tools/
│       └── SKILL.md          # Instructions Claude follows
├── hooks/
│   └── hooks.json            # Event handlers
└── README.md

Important: plugin.json lives inside .claude-plugin/, not at the plugin root. All other directories (skills, hooks, agents) go at the root level.

The plugin.json manifest is actually optional. If you omit it, Claude Code auto-discovers components in the default locations and derives the plugin name from the directory name.

Hot reloading: Changes to skills are picked up automatically during a session. Run /reload-plugins to force a refresh without restarting.

What's the Difference Between CLAUDE.md and Skills?

This is the question most builders get wrong, and it has real token cost implications.

	CLAUDE.md	Skills (SKILL.md)
Loading	Always loaded, every session, every turn	On-demand - loads only when task matches
Token cost	Full file size, every message	~100 tokens idle, ~5K active
Best for	Project facts: tech stack, conventions, architecture rules	Procedures: code review checklists, deploy workflows, scaffolding
Scope	One file per project	Multiple skills, portable across projects
Mental model	"Project brain" - what Claude needs to know	"Reusable capabilities" - what Claude needs to do

The rule of thumb: if you start your thought with "In this project, we always..." it belongs in CLAUDE.md. If you're describing a multi-step workflow that only applies sometimes, that's a skill.

If your CLAUDE.md has grown past 500 lines with detailed instructions for 10 different tasks, you're paying full token cost on every message for procedures that are rarely relevant. Move those into skills that load on demand.

Together, CLAUDE.md and skills give you the full picture: CLAUDE.md handles project-level context; skills handle reusable behavior. You can version-control how Claude behaves on your project the same way you version-control your code.

What Can You Build With Claude Code Skills?

1. Convention enforcement. The example above. Stop re-explaining naming rules, folder structure, and code style every session. Write it once in a SKILL.md, commit it, done.

2. Custom slash commands. Define /deploy, /review, or /test as skill-backed commands that run your specific workflow steps. Claude executes them consistently knowing exactly what your project needs.

---
name: deploy
description: Run the production deployment checklist for this project.
---

## Deploy Checklist
1. Run npm test and confirm all tests pass
2. Check for uncommitted changes with git status
3. Build production bundle with npm run build
4. Run ./scripts/deploy-prod.sh
5. Verify health check at https://api.example.com/health

3. Safe audit workflows with disallowed-tools. Skills can restrict which tools Claude has access to while active. Build a read-only code review skill:

---
name: code-review
description: Review code for quality issues without making changes.
disallowed-tools: Bash, Write, Edit
---

Review the code and report issues. Do not modify any files.
Focus on: type safety, error handling, test coverage gaps,
and potential security issues.

The disallowed-tools frontmatter (shipped in v2.1.152) removes listed tools from Claude's available pool entirely while the skill is active. This is least-privilege at the skill layer, not just a prompt instruction.

4. Shared agent patterns. If your team has a debugging workflow, a PR checklist, or a data migration process that works, encode it once. The next person who touches that code path gets the same starting point. Personal skills (~/.claude/skills/) travel with you across projects. Project skills (.claude/skills/) travel with the repo.

Skills vs Plugins: When Do You Need a Full Plugin?

A common source of confusion. Here's the distinction:

	Simple Skill	Full Plugin
Minimum files	1 (SKILL.md)	1 (SKILL.md) + optional .claude-plugin/plugin.json
Can include	Instructions only	Skills + agents + hooks + MCP servers + custom commands
Namespace	/skill-name	/plugin-name:skill-name
Best for	Single-purpose instructions	Multi-component toolkits to share with teams
Scaffold with	mkdir + create SKILL.md	claude plugin init <name>

Start with a simple skill. You can always upgrade to a full plugin later by adding a .claude-plugin/plugin.json manifest and additional component directories.

The Bigger Picture: Behavior as Code

This update is part of a shift happening across Claude Code. Agent behavior is moving toward something you can version, review in PRs, and roll back:

• Skills in .claude/skills/ for reusable capabilities
• CLAUDE.md for project context
• Hooks for event-driven automation (pre/post tool execution)
• Agents (subagent definitions) for specialized task delegation
• Dynamic Workflows for parallel task orchestration

The direction is clear: the way Claude behaves on your project should be as reproducible as your CI pipeline. Commit your .claude/ directory. Code review changes to skills the same way you code review application logic.

This update - auto-loading from .claude/skills/ without marketplace friction - removes the last significant barrier to treating agent behavior as first-class project infrastructure.

Other Fixes in v2.1.157

A few stability improvements worth knowing about:

• Fixed background agents not reporting the correct date after sleep/wake resume
• Fixed --resume not properly restoring background subagents
• EnterWorktree can now switch between Claude-managed worktrees mid-session
• Worktrees are left unlocked when the agent finishes
• claude agents dispatched sessions now honor the agent field in settings.json
• Fixed right-click paste duplicating clipboard in VS Code, Cursor, and Windsurf integrated terminals
• WSL: fixed image paste and screenshot paste on Windows 11
• /terminal-setup now disables GPU acceleration in integrated terminals to prevent garbled text rendering

Full changelog: github.com/anthropics/claude-code/releases/tag/v2.1.157

Key Takeaways

• Claude Code v2.1.157 auto-loads skills and plugins from .claude/skills/ - no marketplace, no flags, no config.
• Simplest setup: create a folder with a single SKILL.md file. That's a valid skill.
• CLAUDE.md = always-on project facts. Skills = on-demand procedures. Use both, but know which is which.
• disallowed-tools frontmatter lets you enforce least-privilege at the skill level (e.g., read-only code review).
• Commit .claude/skills/ to git. Every team member gets the same Claude behavior from day one.
• Start simple. One SKILL.md file. Upgrade to a full plugin with claude plugin init when you need agents, hooks, or MCP servers.

Free Course: Master AI Agent Engineering

Skills solve how you give Claude persistent project knowledge. But they're one piece of a bigger system. Why does Claude drift from conventions when context gets long? Why does stuffing more instructions into CLAUDE.md sometimes make the agent worse? Why does a 50-tool system break down when a 10-tool system worked fine?

These are all context engineering problems - and they're covered in depth in the free 10-day AI Agent Engineering course.

The course covers the full stack - from agent loops and tool systems to context engineering and memory. One lesson per day, delivered to your inbox. 1,200+ builders have already completed it.

• Day 1-2: The 6-pillar framework behind every production agent (Claude Code, Cursor, Manus)
• Day 3-5: Agent loops, tool systems, and context engineering - with real code
• Day 6-8: Memory, multi-agent orchestration, and the harness that holds it together
• Day 9-10: Ship a working agent + career playbook

Skills fit into two pillars directly: Context Engineering (Day 4 - progressive disclosure, on-demand loading, managing token budgets) and Harness Engineering (Day 8 - permission systems, disallowed-tools, lifecycle hooks). Understanding these pillars is what makes the difference between "I dropped a SKILL.md and it worked" and "I designed a skills architecture that scales across 15 engineers."

Start the Free Course

Want to go deeper on Claude Code workflows, skills architecture, and the context engineering principles behind them? Join AI Builder Club for the full course, live workshops, and a community of 1,200+ builders shipping AI products.

Join AI Builder Club →

Source: Claude Code v2.1.157 release notes, May 29, 2026. Claude Code Skills documentation. Claude Code Plugins documentation.