Claude Code Skills Getting Started Guide, 2026 Let the AI ​​programming assistant remember your project specifications

Most people who have used Claude Code have run into the same annoyance: every time you open a new session, you have to tell it all over again what tech stack the project uses, what the code style is, what the testing requirements are, and which directories must not be touched. After repeating this a few times, efficiency drops instead of rising. The Skills mechanism that Claude Code provides (also called the project-spec file, CLAUDE.md) exists precisely to solve this problem. Write down the project's common knowledge once and place it in the agreed-upon location, and from then on every time you start Claude Code it will read it automatically, so you don't have to repeat yourself. This article explains how to write a good CLAUDE.md so your AI coding assistant truly remembers your project.

1. What Are Claude Code Skills

Claude Code is a command-line AI coding tool made by Anthropic that lets developers interact with the Claude model in the terminal through natural language to complete coding tasks. Skills is a mechanism Claude Code provides that lets you write project-level context, style conventions, and operational constraints into a fixed file, which Claude Code loads automatically on startup.

The standard name for this file is CLAUDE.md, and placing it in the project root directory makes it take effect. Besides the project level, Claude Code also supports user-global-level Skills configuration, usually in the .claude folder under the user's home directory. The former applies to a specific project, the latter applies to all of this user's projects.

Skills isn't just a simple README. It's more like a working manual for the AI assistant, telling it which rules to follow in this project, which practices to prefer, and which operations to avoid. Well-written Skills can raise the quality of Claude Code's output by a tier, because it will no longer use the wrong framework version, the wrong naming style, or the wrong test suite.

2. Why You Need Skills: The Pain of Repeated Explanation

If every time you start a new conversation with Claude Code you have to first say "this project uses TypeScript strict mode, no any allowed, tests use Vitest not Jest," then you're already hardcoding Skills with your mouth, just without solidifying it.

The cost of repeated explanation isn't only typing time. More seriously, the human brain forgets. Today you said no any, tomorrow you might forget to say it again, and of course Claude Code won't know. The result is that you only discover a pile of any when merging the code, and you either fix it or argue about it. Solidifying these rules into CLAUDE.md bypasses the unreliable human-brain link.

A deeper problem is team collaboration. The same project may have several people using Claude Code, and everyone gives it different instructions. A thinks function names should be camelCase, B thinks underscores, C lets the AI write to its own taste. The result is messy code style, painful reviews, and uneven quality. A shared CLAUDE.md makes this private tacit understanding explicit, so the AI works by the same set of rules in everyone's session.

Another kind of pain point is high-frequency pitfalls. Certain operations simply must not be done in this project, like directly editing a generated file, directly git pushing to main, or directly dropping a database table. These are taboos accumulated from lessons learned, but the AI assistant doesn't know them. Writing them into Skills is like installing guardrails for it, significantly lowering the error rate.

3. Where to Put the CLAUDE.md File

The most common location is the project root directory, with the filename CLAUDE.md. On startup, Claude Code automatically searches upward from the current working directory for this file and loads it once found. This is project-level Skills, with a scope limited to the current project.

The user-global level is usually placed at .claude/CLAUDE.md in the home directory (the exact path is subject to the official documentation and may differ slightly across versions). Global Skills take effect in all projects, suiting preferences unrelated to a specific project but where your personal style is strong, such as code-comment language, default commit-message style, and some general behavioral constraints.

If both a project-level and a user-level CLAUDE.md exist, they generally take effect additively. Project-level rules have higher priority and override the conflicting parts of the global one. The exact merge rules are subject to the tool's latest behavior.

Subdirectory Skills is also a use case. In some large monorepos, different subdirectories have very different tech stacks and styles. You can place a separate CLAUDE.md in each subdirectory, and Claude Code will load the corresponding one based on the current working directory. This caters to overall consistency while leaving flexibility for each module.

CLAUDE.md is itself an ordinary Markdown file and can be put under git version control. The advice is to bring the project-level CLAUDE.md under version control, so team members get the same set of rules to use directly when they pull the code. The user-level global file is managed in your own dotfiles repository.

4. What a Standard CLAUDE.md Should Contain

Different projects have different emphases, but the following categories of content are useful for most projects.

Tech-stack description. Right at the start, write clearly what language, what framework, and what version this project uses (a rough version, no need to be precise to the patch number). For example, Node 18 plus TypeScript strict mode, React 18 plus Vite, backend Go 1.22 plus PostgreSQL. These few lines let the AI skip the repeated-guessing step.

Directory structure and responsibilities. Briefly list the division of labor for the main directories. For example, src/components for UI components, src/services for business logic, src/utils for pure-function utilities, tests for test files, scripts for deployment scripts. Once the AI knows these, it automatically puts new files in reasonable places.

Naming and code style. Write down the conventions for function naming, file naming, and variable naming. State directly what tool you use for code formatting (something like Prettier, ESLint, or Biome). If there are syntax or patterns forbidden in the project (such as no default export, no var, no console.log into the main branch), list them all here.

Testing requirements. Which test framework, where test files go, whether new features must come with tests, and what the test-coverage floor is. The AI won't know these things unless you ask; telling it avoids a lot of rework.

Forbidden operations. The most important category of content. Clearly write out what absolutely must not be done. For example, no direct push to main, no skipping the pre-commit hook, no running migration scripts in the production environment, no deleting certain directories. The AI will proactively steer clear when it sees these.

Workflow conventions. Git branch naming rules, commit-message style, PR description templates, and key points of the code-review process. All of these can be written into Skills so the AI gets it right in one go when helping you create a branch or write a commit message.

Special background knowledge. Those implicit conventions passed by word of mouth in the project, the things newcomers don't know unless taught. For example, a variable name is actually a legacy abbreviation, an interface's name carries a special meaning, or a constant's value absolutely must not be changed. Write this kind of knowledge down so the AI can work like a veteran employee.

5. Five Principles for Writing Good Skills

The first principle: write rules, not reasons. Skills is a working manual for the AI, not a design document for people. Express each rule in the shortest possible sentence, and don't explain why. For example, write directly "tests use Vitest not Jest," not "because Jest's config is complex and slow to start, we chose Vitest." The AI doesn't need reasons; it needs clear instructions.

The second principle: negative rules matter more than positive rules. The AI can guess "what must be done" pretty well on its own, but it will fall into pitfalls on "what absolutely must not be done" if it doesn't know. Listing the taboos separately, marked with an obvious indicator, works best.

The third principle: be specific to the point of being executable. Abstract statements are useless. Don't write "code should be readable," write "functions no longer than 50 lines, nesting no deeper than 3 levels, no single-letter variable names (except loop variables)." Quantifiable rules are easy to execute.

The fourth principle: update regularly. Skills isn't write-once-and-forget. The project evolves, the tech stack changes, the rules change. The advice is to go through CLAUDE.md monthly or quarterly, deleting the outdated and adding newly emerged conventions. Like code, Skills also needs maintenance.

The fifth principle: control the length. A CLAUDE.md that's too short can't play its role, while one that's too long dilutes the AI's attention. The advice is to keep the core-rules section between 1,000 and 3,000 characters, putting content that truly needs elaboration in separate documents and listing only a reference link in Skills.

6. A Sample Skills Template for Individual Developers

Below is a simplified individual-project template you can modify and use.

In the tech-stack section, write clearly: this project uses Python 3.11 plus FastAPI plus SQLAlchemy 2.0 plus PostgreSQL, all code is formatted with ruff, and type annotations are checked with mypy strict mode.

In the directory-conventions section: app/api for routes, app/services for business logic, app/models for data models, app/utils for utility functions, tests for test code, scripts for one-off scripts.

In the code-style section: functions and variables use snake_case, class names use PascalCase, constants use UPPER_CASE. Functions get complete type annotations, in-module functions are no longer than 50 lines, and files are no longer than 500 lines.

In the testing-requirements section: new features must come with pytest tests, with test files named test_*.py. Tests involving the database use fixtures for isolation and don't connect to the real database.

In the taboos section: no using print for debugging (use logging instead), no directly modifying existing alembic migration files, no skipping the pre-commit hook, no direct push to the main branch.

In the workflow section: open a new branch for each feature, with branches named feat/xxx or fix/xxx. Commit messages use the short present tense (English or Chinese is fine, but be consistent with one within a project). PRs must include a brief description and test results.

Write it out by this template and you'll find a CLAUDE.md comes to roughly 800 to 1,500 characters, with very high information density. After reading it, the AI assistant's output style will be much more consistent with yours.

7. Sharing Skills in Team Collaboration

In team-collaboration scenarios, the value of CLAUDE.md is amplified several times over. A shared Skills keeps everyone's collaboration with the AI consistent.

Step one, bring CLAUDE.md under git version control, placed in the repository root. New members automatically get the project spec when they clone, and Claude Code loads it automatically too. This is the lowest-cost way to share.

Step two, maintain a long version of the project spec in the team Wiki or documentation site, with CLAUDE.md as its condensed executable version. People read the long version to understand the background, and the AI reads the condensed version to guide execution. The two complement each other, neither redundant nor missing.

Step three, bring changes to Skills into the code-review process. Modifying CLAUDE.md also goes through the PR process and merges only after someone reviews and approves. This avoids one person casually changing a rule and causing inconsistent AI behavior within the team.

Step four, review regularly. The advice is for the team to go through CLAUDE.md monthly or quarterly, discussing which rules are outdated and which newly emerged pitfalls need adding. Maintain Skills as part of the team's engineering culture rather than one person's personal config.

Step five, allow submodule differentiation. In large projects, the rules for the frontend, backend, data, and algorithm teams may differ greatly. Beyond the main CLAUDE.md, each subdirectory can hold its own CLAUDE.md. Claude Code loads the nearest one by working directory in priority.

8. Common Mistakes: What Not to Turn Skills Into

The first mistake: turning it into a project introduction. CLAUDE.md isn't a README; don't spend big paragraphs on project background, business value, or team intros. This information doesn't help the AI write code and instead takes up its attention. Put background content in the README and work constraints in Skills, with responsibilities separated.

The second mistake: piling up empty talk. "Code should be concise, comments clear, naming accurate"—writing this is as good as not writing it. The AI is already trained to pursue these qualities, and writing it once just wastes tokens. If you're going to write, write specific, executable rules.

The third mistake: listing everything in exhaustive detail. Not all project details need to go into Skills. A function's implementation detail or a variable's value range should go in code comments, not be crammed into CLAUDE.md. Skills focuses on project-level conventions, not single-point implementation details.

The fourth mistake: using Skills as an issue tracker. Writing specific tasks like "fix the styling of the login page" or "set the database connection pool to 20 connections" into Skills is entirely inappropriate. Manage tasks with an issue system; Skills holds only long-lasting rules.

The fifth mistake: not maintaining after writing. A Skills written a year ago still mentions an old framework and old spec that were long since replaced, the AI works by the old rules, and the result is a pile of conflicts. Skills is also part of the code and must evolve in sync with it. The advice is to update Skills together with every major version upgrade or tech-stack change.

The sixth mistake: using Skills to express emotion or personal preference. For example, "I especially hate var; if you use var I'll get angry." When the AI sees this tone it adjusts its output style, but the adjustment direction may not be what you want. Just write "no using var; declare variables with const or let" and that's enough. Leave emotional expression for the team chat.

9. Advanced: Tips for Switching Between Multiple Projects and Multiple CLAUDE.md Files

When you maintain multiple projects at the same time, Skills management can be more refined.

The first tip is hierarchical configuration. Put preferences common to all projects into the user-global CLAUDE.md (such as code-comment language preference and general security requirements), and put rules specific to each project into their respective CLAUDE.md. This avoids repeatedly writing the same content in every project.

The second tip is template reuse. If you have multiple similar projects (such as several frontend projects all on Next.js plus Tailwind), you can maintain a template CLAUDE.md, copy and tweak it for new projects. Paired with a script, you can generate the initial Skills for a new project with one click.

The third tip is splitting by role. In the same repository, the working modes of the frontend directory and the backend directory are completely different; after placing a CLAUDE.md in each subdirectory, Claude Code adapts automatically when you switch directories. This is far more efficient than manually telling the AI whether you're currently in the frontend or backend.

The fourth tip is temporary override. If in one session you want to temporarily deviate from one of Skills' rules (such as allowing tests to be skipped just this once), just tell the AI in the conversation; you don't need to go change CLAUDE.md. Skills is the default rules, and a specific session can adjust temporarily.

The fifth tip is auditing changes. Treat CLAUDE.md as an engineering asset and review its history regularly. Which rules were added then removed, which rules' wording was repeatedly adjusted—this information helps you see the evolution path of the team's engineering culture and judge what kinds of rules are truly effective.

Once you're proficient, Skills isn't just a tool for saving your breath but a structured way of precipitating project knowledge. Whether for onboarding newcomers, taking over a project, or switching among multiple projects, the existence of Skills lets the AI assistant get up to speed quickly, and that is its true long-term value.

Frequently Asked Questions

Is a longer CLAUDE.md always better?

No. Too short and it can't play its role; too long and it dilutes the AI's attention. The advice is to keep the core content between 1,000 and 3,000 characters, covering the key sections of tech stack, directory structure, style conventions, testing requirements, and forbidden operations. Put background content that needs elaboration in other documents and keep only the most condensed execution rules in Skills. Go through it every so often, deleting outdated content and adding newly emerged conventions, and the length will naturally stay in a reasonable range.

Can Claude Code still be used without a CLAUDE.md?

Yes. CLAUDE.md isn't mandatory, and Claude Code works fine even if it can't find the file. But without a Skills config, the AI can only guess its understanding of the project from the code context it reads, and the output quality will fluctuate. The advice is to at least write a simple CLAUDE.md (the tech stack plus a few core conventions is enough) and gradually add to it as the project evolves. The time invested is very worthwhile compared with the stability you get in return.

Will the AI definitely follow the rules in Skills?

Most likely, but not 100%. Skills provides strong guidance; the AI prioritizes these rules when generating code, but it still occasionally deviates. If you find a rule is repeatedly violated, you can adjust the wording to make the rule more specific, clearer, and more prominent. You can also turn high-cost-of-violation rules into lint or pre-commit hooks, enforcing them at the tool layer as a supplement to Skills. Combining the two works best.

Could a company project's CLAUDE.md leak internal information?

The content in CLAUDE.md is sent as context to Anthropic's servers when you interact with Claude Code; the specific data handling and privacy policy are subject to the official pages. Don't write highly sensitive information (such as internal interface signatures, credentials, or customer lists) into Skills. You can extract this kind of information into environment variables or a secret manager, with Skills referencing only the variable name and not exposing the value. This way the AI knows such a thing exists without the actual content leaking.

Do Skills for projects in different languages differ in how they're written?

The main difference is in the parts related to the tech stack and toolchain. A Python project would write about ruff, black, mypy, and the like; a Go project would write about gofmt, go vet, and the like; a frontend project would write about ESLint, Prettier, and the like. But the core approach is universal: write clearly the tech stack, directory structure, naming conventions, testing requirements, and forbidden operations. Structurally, Skills for various languages look similar; only the specific rules filled in differ. When taking over a project in a new language, you can first borrow another project's Skills framework, then swap in the specific content for the current language's toolchain.