Claude Code is not a Chatbot… It is an Execution Engine

This is a MarkDown file that exists in the root of your project or Workspace. This file gets fully loaded with every session.

You fill it with all the information Claude needs throughout the session whatever the task is.

For example, the Architecture of the project or the important commands it needs to build. Or file naming conventions. You can also mention the files that Claude should refer to as reference, like for example a Theme file or RoadMap.

There are two viewpoints regarding the size of CLAUDE.md file

• People who say don't let the file exceed 250 lines by much because the entire file gets loaded with the session and therefore will consume a lot of tokens.
• Others who say that this is the most important file and must cover everything even if its size grows.

Personally :

I create more than one CLAUDE.md... So, if my project is modular and I have data - presentation - domain modules. Then I create a CLAUDE.md for each one of them. Instead of one huge file in the root carrying everything about the project. And if the Agent is going to work in one of these modules, it will load its file first thing. Otherwise no.

-----------

These are a group of files whose role is to teach the Agent how to execute specific tasks in the fastest and most economical way. For example:

• How to create a Docx or PDF file and how to modify it
• How to build an mcp server
• How to deal with a database and modify it

Inside the file you give it all the instructions to follow to execute the required skill.

The Skill file is written with YAML format. And at the very beginning of the file there are two very important pieces of information. The name and description.

---
name: create database
description: Create database...
---

Through them the Agent can understand the Skill and use it when it needs it

Notes:

• Unlike CLAUDE.md, the SKILL file is not fully loaded with every session. But Claude loads the appropriate Skill when it needs it only.
• So, does that mean I can add any infinite number of Skills as long as they won't consume tokens?
• The answer is yes. But pay attention to an important point... Remember when we said that the Skill has a name and description?... Well this description, Claude loads with every session for all the Skills existing in the folder. So that with every command it searches if there's a Skill that helps it in executing this command. So if the description is long it might take 100 Tokens for example.
• So you have to be mindful of this matter. True this is a relatively small consumption, but if you have too many Skills, it could be a problem.

---------

These are also a group of files whose function is to define the rules the Agent adheres to while working on specific files. Remember the name and description of Skills?... Well the Rules have another parameter which is paths

---
paths:
- "**/*.kt"
- "**/*.kts"
- "**/android/**/*"
---

Here we're telling the Agent adhere to these rules when you work on files of the mentioned type or in the specified paths. You can then write all the rules after... For example:

- Use data classes for models and DTOs
- Prefer sealed classes for state representations

And any other rules you want

Notes:

• Same as the Skills case, Rules are not loaded except when necessary.
• And also the paths are the only thing that gets loaded with every session so you must be mindful of them.

---

These are of the most important features in Claude. And through them you can shorten dozens of lines of repeated prompts that you use every time.

For example, if every time you start working on a new Ticket you do the following

1. You move the Ticket to 'In Progress'
2. Create a new branch for the feature or fix
3. Execute the feature and modify the required files
4. Open a PR from your branch to the base branch

Then you can simply create a new command called start-feature

Inside this file you will tell Claude all the required steps in order. And afterwards through the chat you say to it:

/start-feature

And that's it.. it will go off and execute all these boring steps and return to you when it finishes.

You might ask, how will it know the ticket number? Or the branch I'm working on right now?.. Surely I'm not going to create a new command for every ticket..

Well, I'll tell you a beautiful thing: this command can take Arguments. Just like the Bash command exactly

Arguments: {ticket} {branch}
Example usage: /start-task 1324 feature/auth_login

Parse the arguments:
First argument: Jira ticket number
Second argument: Working branch

And this way you can send your command any number of Arguments you need.

Notes:

• Unlike all the previous ones, commands don't get loaded at all except at execution time. Not even description. So you can make as many Commands as you want.

-----

[1] Skills

These are the steps required to execute one specific task only. You can't put two skills in the same file.

For example:

• update-jira-ticket: this skill will teach it how to modify the ticket and what data it can modify. And what data it shouldn't modify
• install-android-apk: and here it will teach it how to generate the APK, what adb commands to use to install the APK on the emulator
• reset-data-base: this will teach it how to Access the database, what bash commands to use to drop the database and create it again... example:

---
name: reset-database
description: "This is the manual to how you can reset the current example-database"
---
# Reseting database and repopulating it with updated data.

## Overview
After making any updates to example database scheme you MUST drop the current database and recreate it again and populate it with the updated scheme and initial entries.

## The Process
**Drop the current database:**
- Use this terminal command to drop/delete the current database
```
mysql -h localhost -P 3306 -u root -p***** -e "DROP DATABASE IF EXISTS example_db;"
```

**Recreate a new empty database:**
- Use this terminal command to recreate the database
```
mysql -h localhost -P 3306 -u root -p*** -e "CREATE DATABASE example_db;"
```

**Repopulate database:**
- Use this terminal command to populate the database with updated scheme and initial entries
```
mysql -h localhost -P 3306 -u root -p**** example_db ..
```

[2] Commands

These are ordered actions you define for the Agent inorder to execute a complete task consisting of several missions. And during the execution of these commands the Agent calls the Skills it needs.

For example if I have a task to add a new API and modify data in the database and then test the application on an emulator. Instead of telling the Agent several commands:

• Move Jira ticket 3245 to In Progress ... and wait for it to finish
• Add end-point login-user
• Drop database and recreate it
• Create and install new APK

Now. I can create a command and name it add-end-point as follows

Arguments: {ticket} {branch} {end-point}
Example usage: /add-end-point 2323 feature/new-api login-user

Parse the arguments:
- First argument: Jira ticket number
- Second argument: Working branch
- Third argument: End-point to add

As the Leader agent, orchestrate this feature:
1. Checkout {branch} or create it if not found
2. Read and review Jira ticket PROJ-{ticket}
3. Move ticket to 'In Progress'
4. Make all necessary modification to add the end-point
5. Reset the database
6. Build and install new APK

And with that all I need is to go into the chat and say to claude

/add-end-point 2323 feature/new-api login-user

Notes:

• We can use our Arguments as variables. Like {ticket}
• Step number 2, I didn't tell it how to execute the order. So here it will search in its Skills and find update-jira-ticket and use it
• Same talk in step 5, all I said is Reset the database.. it will search and find reset-data-base and use it
• And the same thing goes with step number 6

----

Here you define all the Agents or roles that Claude will play in your project. There are many examples of this:

Leader - Designer - Code Reviewer - Debugger

With each Agent you determine the shape of its job and what tasks it will do and if there are steps or instructions it needs to follow to execute this job or if there are reference files it needs to look at before working.

Notes:

• Like Skills and Rules. Agents are also YAML formatted..In its Header you determine 3 things:
• The name and description.. as usual so Claude knows the Agent it needs
• The model: and here you specify the AI model for each Agent

For example: it's preferable that the Leader be Opus because it's the one that will organize and divide the work among the rest of the Agents. While the Designer and Code Reviewer can be Sonnet and so on..

You can activate the Agents by saying for example:

Using Leader agent, orchestrate the following ...

At that point the Leader will start reading the task and decide which Agent is appropriate for each stage. And when an Agent finishes, the Leader returns to follow up and hand over to the next agent. And so on.

------