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

Most people who have used Claude Code have encountered the same trouble: every time they open a new session, they have to tell it again what technology stack is used for this project, what is the coding style, what are the testing requirements, and which directories cannot be moved. After repeated several times, the efficiency does not increase but decreases. The Skills mechanism provided by Claude Code (also called the project specification file CLAUDE.md) is to solve this problem. Write the common sense of the project once and put it in the agreed location. Every time you start Claude Code, it will automatically read it, so there is no need to repeat it again. This article talks about how to write a CLAUDE.md so that the AI ​​programming assistant can truly remember your project.

1 What are Claude Code Skills

Claude Code is a command-line AI programming tool produced by Anthropic, which allows developers to complete code tasks through natural language and Claude model interaction in the terminal. Skills is a mechanism provided by Claude Code that allows you to write project-level context, style specifications, and operational constraints in a fixed file, which is automatically loaded when Claude Code starts.

The standard name of this file is CLAUDE.md, and it will take effect when placed in the project root directory. In addition to the project level, Claude Code also supports user global level Skills configuration, usually in the .claude folder in the user's home directory. The former works on specific projects, and the latter works on all projects of this user.

Skills is more than a simple README. It is more like a work manual for the AI ​​assistant, telling it which rules it should abide by in this project, which practices it prefers, and which operations it should avoid. Well-written Skills can improve the output quality of Claude Code to a new level, because it will no longer use the wrong framework version, write the wrong naming style, or use the wrong test suite.

2 Why Skills need to be explained repeatedly

If every time you start a new conversation with Claude Code, you have to say "This project uses TypeScript strict mode and cannot use any. Testing uses Vitest and cannot use Jest." Then you are already hard-coding Skills with your mouth, but it has not been solidified.

The cost of repeating instructions goes beyond typing time. What's more serious is that the human brain can forget things. Today you told me not to use any, but you might forget to say it again tomorrow, and of course Claude Code won't know. As a result, when the code is merged, you find a bunch of any, which must be changed or disturbed. By solidifying these rules into CLAUDE.md, the unreliable aspects of the human brain are bypassed.

The deeper issue is teamwork. There may be several people using Claude Code on the same project, and each person's approach to it is different. A thinks the function name should be camel case, B thinks it should be underlined, and C lets AI write it directly according to its own preferences. The result is a messy code style, painful reviews, and uneven quality. The shared CLAUDE.md can make this private understanding explicit, allowing the AI ​​to work according to the same set of rules in everyone's session.

Another type of pain point is high-frequency pitfalls. Certain operations cannot be done in this project, such as directly changing a generated file, directly git pushing to main, and directly dropping a database table. These are taboos learned from lessons, but the AI ​​assistant doesn’t know them. Writing it into Skills is equivalent to installing guardrails on it, and the probability of errors is significantly reduced.

3 Where is the CLAUDE.md file located?

The most commonly used location is the project root directory, and the file name is CLAUDE.md. When Claude Code starts, it will automatically search for this file from the current working directory and load it when it is found. These are project-level Skills, and their scope is limited to the current project.

The user global level is usually placed in .claude/CLAUDE.md in the home directory (the specific path is subject to the official documentation, and may vary slightly depending on the version). Global Skills will take effect in all projects and are suitable for those that have nothing to do with the specific project but have strong personal preferences, such as code comment language, default submission message style, and some general behavioral constraints.

If both the project level and the user level have CLAUDE.md, it will generally take effect superimposed. Project-level rules have a higher priority and will cover the conflicting parts of the world. The specific merge rules are subject to the latest behavior of the tool.

Skills in subdirectories is also a usage. In some large monorepo, the technology stack and style of different subdirectories vary greatly. You can place a separate copy of CLAUDE.md in each subdirectory, and Claude Code will load the corresponding copy based on the current working directory. This can not only take care of the overall consistency, but also allow flexibility for each module.

CLAUDE.md itself is an ordinary Markdown file, which can be put into git for version management. It is recommended to bring the project-level CLAUDE.md into version control, so that team members can directly use the same set of rules when they pull the code. User-level global files are managed in their own dotfiles warehouse.

4. What should a standard CLAUDE.md contain?

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

Technology stack description. At the beginning, write down clearly what language, what framework, and what version this project uses (rough version, not necessarily 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 sentences allow the AI ​​to skip the guesswork.

Directory structure and responsibilities. Briefly list the division of labor in the main directories. For example, src/components holds UI components, src/services holds business logic, src/utils holds pure function tools, tests holds test files, and scripts holds deployment scripts. After AI knows this, it will automatically place new files in a reasonable location.

Naming and coding style. Function naming, file naming, and variable naming conventions are clearly written. Directly explain what tool to use for code formatting (Prettier ESLint Biome, etc.). If there are syntax or modes that are prohibited in the project (for example, default export is not allowed, var is not allowed, console.log is not allowed to enter the main branch), they are all listed here.

Testing requirements. Which test framework is it? Where are the test files placed? Whether new functions are required to be tested? What is the bottom line of test coverage? The AI ​​doesn't know these things without asking, and telling it can avoid a lot of rework.

Contraindicated operations. The most important type of content. Clearly write out what is absolutely not allowed. For example, it is not allowed to push directly to main, it is not allowed to skip pre-commit hook, it is not allowed to run migration scripts in the production environment, and it is not allowed to delete certain directories. The AI ​​will actively avoid these when seeing them.

Workflow conventions. Git branch naming rules Commit message style PR description template Code Review process points. These can be written into Skills, allowing AI to take shape at once when helping you create branches or write commit information.

Special background knowledge. Those implicit agreements in the project that are passed down by word of mouth are things that newcomers will not know without being taught. For example, a certain variable name is actually a historical abbreviation, the name of a certain interface has a special meaning, and a certain constant cannot be changed. By writing this kind of knowledge down, AI can work like an old employee.

5 Principles for Writing Skills Well

The first principle is to write rules but not reasons. Skills are work manuals for AI, not design documents for humans. Express each rule in the shortest sentence without explaining why. For example, just write "Use Vitest for testing instead of Jest" instead of "We chose Vitest because Jest has complicated configuration and slow startup." AI does not need reasons, it needs clear instructions.

The second principle is that negative rules are more important than positive rules. "What must be done" can be guessed by the AI ​​itself, and "what must not be done" can be misunderstood if the AI ​​doesn't know. List the taboos separately and mark them with obvious signs for the best effect.

The third principle is specific enough to be enforceable. Abstract words are useless. Don't write "the code must be readable", write "the function should not exceed 50 lines, the nesting should not exceed 3 levels, and the variable names should not use single letters (except loop variables)". Measurable rules are easier to implement.

The fourth principle is to update regularly. Skills are not written once and for all. Projects will evolve, technology stacks will change, and rules will change. It is recommended to go through CLAUDE.md every month or quarter, delete outdated ones and make up for new ones. Like code, Skills require maintenance.

The fifth principle is to control the length. If a CLAUDE.md is too short, it will be ineffective, and if it is too long, the AI's attention will be diluted. It is recommended that the core rules should be controlled between 1,000 and 3,000 words. The content that really needs to be discussed can be placed in other documents separately, and only a reference link should be listed in Skills.

6 Examples of Skills Templates for Individual Developers

Below is a simplified personal project template that you can adapt based on.

Write clearly in the technology stack column: This project uses Python 3.11 plus FastAPI plus SQLAlchemy 2.0 plus PostgreSQL. All codes are formatted with ruff, and type annotations are verified with mypy strict mode.

The directory convention is one column: app/api is for routes, app/services is for business logic, app/models is for data models, app/utils is for tool functions, tests is for test codes, scripts is for one-time scripts.

Coding style column: Use snake_case for functions and variables, PascalCase for class names, and UPPER_CASE for constants. Add complete type annotation to the function, the function in the module should not exceed 50 lines, and the file should not exceed 500 lines.

Test requirements column: New functions must be tested with pytest, and the test file is named test_*.py. Tests involving the database are isolated using fixtures and not connected to the real database.

Taboo column: It is not allowed to use print debugging (use logging instead). It is not allowed to directly modify the existing migration files of alembic. It is not allowed to skip the pre-commit hook. It is not allowed to push directly on the main branch.

Workflow column: Open a new branch for each function, and name the branch feat/xxx or fix/xxx. Submit information in the short present tense (either English or Chinese are acceptable, but the same one is used for the same project). The PR must include a brief description and test results.

After writing according to this template, you will find that a CLAUDE.md is about 800 to 1500 words long, and the information density is very high. After the AI ​​assistant reads it, the style of the generated code will be much consistent with yours.

7 Skills sharing in team collaboration

In a team collaboration scenario, the value of CLAUDE.md is magnified several times. A shared set of skills allows everyone to collaborate with the AI ​​on the same caliber.

The first step is to incorporate CLAUDE.md into git version management and place it in the root directory of the warehouse. New members will automatically have project specifications after cloning, and Claude Code will also be automatically loaded. This is the lowest cost way to share.

The second step is to maintain a long version of the project specification in the team Wiki or documentation site, with CLAUDE.md as its streamlined execution version. Humans read the long version to understand the background, and AI reads the condensed version to guide the execution. The two complement each other and are neither redundant nor missing.

The third step is to incorporate changes in Skills into the Code Review process. Modifying CLAUDE.md also requires a PR process, and it will only be merged if someone reviews it. This prevents someone from casually changing the rules and causing inconsistent AI behavior within the team.

The fourth step is to review regularly. It is recommended that the team review CLAUDE.md once a month or quarterly to discuss which rules are outdated and which new pitfalls need to be fixed. Maintain skills as part of the team's engineering culture, not as one person's personal configuration.

The fifth step is to allow differentiation of sub-modules. In large-scale projects, the rules of each group of front-end, back-end data and algorithms may be very different. You can put your own CLAUDE.md in each subdirectory besides the main CLAUDE.md. Claude Code will load the latest one based on the working directory first.

8 common misunderstandings: Don’t write Skills like this

The first misunderstanding is writing a project introduction. CLAUDE.md is not a README. Don't spend a lot of time talking about the project background, business value, and team introduction. This information does not help AI write code, but takes up its attention. Put background content in README, work constraints in Skills, and separate responsibilities.

The second misunderstanding is written as a pile of empty words. The code should be concise, the comments should be clear, and the naming should be accurate. If you write this, it means you haven’t written it. AI has been trained to pursue these qualities, and writing it once is just a waste of tokens. If you want to write, write specific and executable rules.

The third misunderstanding is to list everything in detail. Not all project details need to be written into Skills. The implementation details of a certain function and the value range of a certain variable should be placed in code comments and should not be squeezed into CLAUDE.md. Skills focuses on project-level conventions, not single-point implementation details.

The fourth misunderstanding is to use Skills as an issue tracker. It is completely inappropriate to enter specific tasks such as "fix the style of the login page" and "adjust the database connection pool to 20 connections" into Skills. Tasks are managed using the issue system, and Skills only contains long-term rules.

The fifth misunderstanding is not maintaining it after writing it. The Skills written a year ago still mentions the old framework and old specifications that have been replaced long ago. AI works according to the old rules, resulting in a lot of conflicts. Skills are also part of the code and must evolve simultaneously with the code. It is recommended to update Skills with every major version upgrade or technology stack adjustment.

The sixth misunderstanding is using Skills to express emotions or private preferences. For example, "I really hate var. I get angry when I use var." When AI sees this tone, it will adjust the output style, but the adjustment direction may not be what you want. Just write "var is not allowed, use const or let for variable declaration" is enough, and leave emotional expression to the team chat.

9 Advanced multi-project and multiple CLAUDE.md switching techniques

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

The first technique is hierarchical configuration. Put the common preferences of all projects into the user's global CLAUDE.md (such as code comment language preferences and general security requirements), and put the unique rules of each project into their own CLAUDE.md. This avoids writing the same content repeatedly in every project.

The second technique is template reuse. If you have multiple similar projects (for example, several front-end projects based on Next.js and Tailwind), you can maintain a template CLAUDE.md and directly copy and modify it for new projects. With the script, you can generate the initial skills of a new project with one click.

The third technique is to segment by role. The working modes of the front-end directory and the back-end directory in the same warehouse are completely different. After placing a copy of CLAUDE.md in each subdirectory, Claude Code will automatically adapt when you switch directories. Much more efficient than manually telling the AI ​​whether it is currently on the front end or the back end.

The fourth technique is temporary coverage. In a certain session, if you want to temporarily deviate from a certain rule of Skills (for example, allowing you to skip the test just this time), you can tell the AI ​​directly in the conversation without changing CLAUDE.md. Skills are the default rules, specific sessions can be adjusted temporarily.

The fifth technique is to audit changes. Treat CLAUDE.md as a project asset and review historical changes regularly. Which rules have been added and removed, and which rules' wording has been repeatedly adjusted. This information can help you see the evolution path of the team's engineering culture, and can also help you judge what kind of rules are really effective.

Once you are proficient, Skills is not just a tool to save your words, but a structured way to accumulate project knowledge. When new people join, take over projects, and switch between multiple projects, the existence of Skills can allow the AI ​​assistant to quickly enter the state. This is its real long-term value.

FAQ

CLAUDE.md Is the longer the better?

no. Too short will not be of value, and too long will dilute the AI's attention. It is recommended that the core content be controlled between 1,000 and 3,000 words, covering several key areas including technology stack, directory structure, style specifications, testing requirements, and taboo operations. The background content that needs to be expanded is placed in other documents, and only the most refined execution rules are placed in Skills. Go through it every once in a while, delete outdated content, and make up for new agreements, so that the length can naturally be kept within a reasonable range.

Can Claude Code still be used without CLAUDE.md?

It can be used. CLAUDE.md is not mandatory, Claude Code can work normally even if it cannot find this file. But without Skills configuration, AI’s understanding of the project can only rely on guessing from the code context it reads, and the quality of the output will fluctuate. It is recommended to write at least a simplified version of CLAUDE.md (just add a few core conventions to the technology stack), and gradually add it as the project evolves. The time invested is very cost-effective compared with the stability return.

Will AI definitely abide by the rules in Skills?

Most likely, but not 100%. Skills provide strong guidance, and the AI ​​will give priority to following these rules when generating code, but it will still occasionally deviate. If you find that a certain rule is violated repeatedly, you can adjust the writing to make the rule more specific, clear, and prominent. You can also make high-cost violation rules into lint or pre-commit hooks, and enforce them from the tool layer as a supplement to Skills. A combination of the two works best.

Will the internal information involved in the company's CLAUDE.md project be leaked?

The content in CLAUDE.md will be sent to Anthropic's services as context when you interact with Claude Code. For specific data processing and privacy policies, please refer to the official page. Content involving highly sensitive information (such as internal interface signatures, credentials, and customer lists) should not be written into Skills. This kind of information can be extracted into environment variables or secret managers. Skills only references the variable name and does not expose the value. This allows the AI ​​to know that there is such a thing without revealing the actual content.

Is there any difference in writing skills for projects in different languages?

The main difference is in the parts related to the technology stack and tool chain. For Python projects, you should write ruff black mypy and the like, for Go projects, you should write gofmt go vet and the like, and for front-end projects, you should write ESLint Prettier and the like. But the core idea is universal: clearly write down the technology stack, directory structure, naming conventions, test requirements, and taboo operations. Structurally, Skills in various languages ​​look similar, but the specific rules for filling in are different. When taking over a new language project, you can first learn from the Skills framework of other projects, and then replace the specific content according to the tool chain of the current language.