Claude Code — Anthropic’s agentic coding tool in your terminal

What it is

Claude Code is an agentic coding tool made by Anthropic: you describe a task in plain words, and it reads your files, edits code and runs commands, asking for permission first. It runs in the terminal, and you can also use it in code editors such as VS Code and JetBrains, in the Claude desktop app and on the web.

What you need

• An account: a Claude Pro, Max, Team or Enterprise plan, or a Console (API) account. The free claude.ai plan does not include Claude Code.
• A computer: macOS 13 or later, Windows 10 (1809) or later, Ubuntu 20.04 or Debian 10 or later, at least 4 GB of memory, and an internet connection.
• A project folder to work in — ideally a Git repository, so every change can be reviewed and undone.

Install

On macOS, Linux and WSL run the first line; on Windows run the PowerShell line. Installed this way, it updates itself in the background. Homebrew and WinGet installs do not update by themselves.

macOS · Linux · WSL

curl -fsSL https://claude.ai/install.sh | bash Copy

Windows PowerShell

irm https://claude.ai/install.ps1 | iex Copy

Homebrew

brew install --cask claude-code Copy

WinGet

winget install Anthropic.ClaudeCode Copy

npm (Node.js 22+)

npm install -g @anthropic-ai/claude-code Copy

Check the installation

Open a new terminal window. claude --version should print a version number, and claude doctor shows the state of the installation. If you see “command not found”, open the terminal again and check your PATH.

First run — five steps

1. Open a terminal and go to your work folder: an existing project with cd <folder>, or a new empty folder with the commands below. Then type claude and press Enter (this starts the command-line tool, not the desktop app). The first time, a browser opens so you can log in.
2. Existing project: ask “What is in this project?” so it reads the project. Empty folder: say what you want to make, for example “I want a one-page website that shows today’s date. How should we start?”
3. Existing project: run /init to create CLAUDE.md, then add your test command and the rules to follow. Empty folder: skip this step for now, because /init needs code to read. Run it once the project has files.
4. Type /plan (or press Shift+Tab until plan mode shows) and ask for a change; in an empty folder, ask for the first files. Before you approve, check which files it will change and which commands it will run. Approve only what belongs to the job you asked for. If anything else is there, correct the plan first.
5. See what changed with git status (new files) and git diff (edited files), check the result yourself, for example by running the tests, then commit.

Existing project

New project (empty folder)

Basic practice — try it once from the start

If you get stuck: if claude does not start, check the install with claude doctor; if the sign-in page does not open, close the terminal, open a new one and run claude again. Done all five? Move on to the [Intermediate] tab.

Learn more on SONUB

• Claude Code 1: set up a project and give lasting instructions
• Claude Code 2: plan, change, test, review
• Agents and sub-agents: how an AI works step by step
• Goal and Ralph Loop: let an agent keep going until it is really done
• The claude-skill agent skill — learn Claude Code step by step and keep up with new features

Official documentation

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows
• Claude Code — Use Claude Code with Chrome

Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.

Models and effort — which to use (recommended: Opus 5.5, High)

As of November 2026, use Opus 5.5 at High effort for development. Its default effort is medium, so set it as below or run /model opus and /effort high. Every model and effort level, and when to go lower or higher, is in Recommended use on Tool Master.

{
  "model": "opus",
  "effortLevel": "high"
}

claude --model opus --effort high

# inside Claude Code
/model opus
/effort high

• Recommended models — Tool Master

CLAUDE.md — project instructions read every session

CLAUDE.md is a Markdown file that Claude Code reads every time a session starts. Write down what you are tired of repeating: build and test commands, code rules, things it must not do. Run /init and it reads the project and writes a first CLAUDE.md. CLAUDE.md files in several places do not override each other — they are all read together.

• ~/.claude/CLAUDE.md — your personal instructions for every project
• ./CLAUDE.md or ./.claude/CLAUDE.md — project instructions the team shares (commit it to Git)
• ./CLAUDE.local.md — instructions only you use in this project (add it to .gitignore)
• CLAUDE.md in a subfolder — also read when Claude reads or edits files in that folder. Rule files in .claude/rules/ can apply to certain files only, with paths
• Note: if a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working folder or any folder above it, Claude Code does not read AGENTS.md. Your personal ~/.claude/CLAUDE.md does not count — see the next section.

# My App

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode. Do not use `any`.
- Put new API routes in src/routes/.
- Never edit files in vendor/.
- Run the tests before you say a task is done.

@docs/architecture.md

Keep it short (the official docs suggest under 200 lines). It is read every time, so a long file takes up room and buries the important rules. /memory shows the instruction files that were loaded and opens them for editing, and @path (like @docs/architecture.md) pulls in another file. If you use several AIs together, it is best to keep only AGENTS.md in the project instead of CLAUDE.md — see the section right below.

Use only AGENTS.md — so every AI works from the same instructions

Why do this? If one project uses other AIs such as Codex, Cursor or Gemini alongside Claude Code, separate instruction files for each tool soon drift apart. AGENTS.md is an open format that many coding agents read. Write the rules once in AGENTS.md and every AI follows the same instructions, whichever one you work with. The method below exists for exactly this — so that in one project, many AIs all use the same instructions through AGENTS.md.

Claude Code can read AGENTS.md directly too (v2.1.277 or later), but not quite like CLAUDE.md.

• With the default setting it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working folder or any folder above it. Adding just one CLAUDE.local.md for personal notes stops AGENTS.md from being read (~/.claude/CLAUDE.md and .claude/rules/ do not count here).
• Claude reads a subfolder's AGENTS.md when it opens an existing file in that folder with the Read tool and that folder has no CLAUDE.md of its own. If Claude creates a new file there before reading an existing file, it may not have loaded the folder's instructions yet. A subfolder's CLAUDE.md is loaded when Claude reads, creates or edits files there.
• AGENTS.local.md, AGENTS.override.md and files under a .agents/ folder are not read, and neither is the AGENTS.md of a folder added with --add-dir.

The best way is not to use CLAUDE.md in the project folder at all and use only AGENTS.md. Your global instructions in ~/.claude/CLAUDE.md are still loaded by default, and in the project folder AGENTS.md is used. Other AIs such as Codex read the same AGENTS.md, so you edit the rules in one place only — AGENTS.md.

But if you use CLAUDE.md in even one place — the project folder, the current folder, a parent folder or a subfolder — you must use CLAUDE.md in every folder. If there is even one CLAUDE.md in the working folder or above it, Claude Code does not read AGENTS.md, so mixing them means some folders' rules are read and others are left out. If you still want to use AGENTS.md in that case, just add one line, @AGENTS.md, to each CLAUDE.md. @path is the syntax that pulls a file's contents in at that spot, and the official docs say this import never makes Claude read AGENTS.md twice.

1. Write the shared rules (install and test commands, code rules, things not to do) in AGENTS.md at the top of the project. You can also create it with Codex's /init.
2. Do not create CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere in the project (not in the current folder, parent folders or subfolders).
3. Keep your personal instructions for every project in ~/.claude/CLAUDE.md — it is always loaded together with AGENTS.md.
4. If a subfolder has its own rules (for example api/), put an AGENTS.md there as well.
5. Open /memory in Claude Code and check that AGENTS.md was loaded. If you decided to use CLAUDE.md, also check that every folder's CLAUDE.md has the one line @AGENTS.md.

~/.claude/CLAUDE.md    ← your personal rules (still loaded by default)

my-project/
├── AGENTS.md          ← shared rules for every AI (Claude Code, Codex, Cursor, Gemini …)
└── api/
    └── AGENTS.md      ← rules only for api/

(no CLAUDE.md anywhere in the project)

my-project/
├── AGENTS.md
├── CLAUDE.md          ← @AGENTS.md
└── api/
    ├── AGENTS.md
    └── CLAUDE.md      ← @AGENTS.md

@AGENTS.md

Good to know, and other ways. ① Set Project instructions in /config to claude-md-and-agents-md and each folder's AGENTS.md is read right after its CLAUDE.md. ② A symbolic link (ln -s AGENTS.md CLAUDE.md) also works, but with Windows in the mix the one line @AGENTS.md is safer.

• The order in which Codex reads AGENTS.md — Codex Intermediate

Permissions and modes — decide what it may do without asking

Claude Code asks before it edits a file or runs a command. If approving the same thing every time gets tiresome, turn it into a rule, and switch modes to suit the job.

• Shift+Tab — switch modes: default (ask every time) → acceptEdits (file edits without asking) → plan (read only and show a plan). If you started in auto mode, the first press switches to default.
• /permissions — see and edit the allow, ask and deny rules and which file each one comes from.
• .claude/settings.json holds rules the team shares (commit it), .claude/settings.local.json holds rules only you use, and ~/.claude/settings.json holds rules for all your projects.
• Rules are checked in the order deny → ask → allow. Anything denied anywhere cannot be allowed elsewhere, so block secret files such as .env with deny.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

bypassPermissions (--dangerously-skip-permissions) turns every check off. Use it only where damage does not matter, such as a container or virtual machine with no internet access.

Managing context — when the conversation gets long

How much Claude can see at once (the context window) is fixed. The conversation, the files it read and command output all pile up there, and when it is full the earlier part gets summarized. The longer it grows, the fainter earlier instructions become, so make tidying up a habit.

• /context — see, as coloured blocks, what is taking up the context and how much.
• /compact — summarize the conversation so far to free up room. You can say what to keep (for example /compact focus on the login bug fix).
• /clear — start a new conversation with empty context when you begin unrelated work. The earlier conversation is not deleted: /resume brings it back.
• claude -c continues the last conversation in this folder, and claude -r or /resume lets you pick an earlier one to continue.
• Esc twice (or /rewind) — pick an earlier point from the checkpoint list and roll back the conversation and code. Files deleted or moved with Bash are not restored, so it does not replace Git commits.

One job per conversation. When the job changes, starting fresh with /clear is the easiest way to tidy up.

Save context — set Claude Code to auto compact at 444k (SONUB setting)

Asking well — where, what and how to check

• Vague request: "Fix the login"
• Clear request: "In @app/Http/Controllers/LoginController.php a wrong password gives a 500 error. Make it return 422 with an error message, add a test to tests/Feature/LoginTest.php and check that it passes."

• Type @ to pick a file and attach it to your request (@src/login.ts).
• For error screens and design mock-ups, paste or drag in a screenshot.
• For a big job, enter plan mode first with /plan (or Shift+Tab). Claude looks through the code and writes a plan, and edits no files until you approve it.
• For a hard problem, raise the model and effort level in /model, or put ultrathink in your request so it thinks harder on that turn only.
• /goal <finish line> — Claude keeps taking turns without a new request until the finish line is met (e.g. /goal all tests in tests/ pass, or stop after 20 turns). /goal alone shows the status; /goal clear removes it.

Best practices — how Anthropic recommends using Claude Code

In short: give Claude a way to check its work, plan hard work first, be specific, keep CLAUDE.md short, and use /clear when you switch to a new, unrelated task — keep the current context for related follow-up work. The six good habits from both official guides, with commands for Claude Code and Codex, are in Recommended use.

• Six good habits — Tool Master

Common mistakes — and how to fix them

The official guide warns about five failure patterns — the kitchen-sink session, correcting over and over, an over-long CLAUDE.md, trusting without checking and endless exploration. All ten mistakes from both guides, each with its fix, are in Recommended use.

• Ten common mistakes — Tool Master

Intermediate practice — try it in your own project

1. Create an AGENTS.md file in your project's root directory with the test command and three rules, and check that there is no CLAUDE.md in the project.
2. Open /memory and check that AGENTS.md and ~/.claude/CLAUDE.md were loaded.
3. In .claude/settings.json allow one test command and deny .env, then check with /permissions.
4. Ask for one small feature in plan mode, read and adjust the plan, then approve it.
5. Look at how much is used with /context, shrink it with /compact and look again.

Done all five? Finally, use /clear if you are ready to move on to a new, unrelated task — then go to the [Advanced] tab.

Official documentation

• Use Claude Code with Chrome
• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing
• Model configuration — auto-compact window
• Best practices
• Best practices — common failure patterns

Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.

Agent skills — teach it jobs you repeat

A skill is a folder with a SKILL.md in it. Normally Claude knows only each skill's name and description; when a job matches the description, it reads the body and follows it. So many skills take up almost no room. The old custom commands (.claude/commands/) have now been merged into skills.

• .claude/skills/<name>/SKILL.md is for this project, ~/.claude/skills/<name>/SKILL.md for all your projects.
• Say clearly in description what it does and when to use it, so Claude picks it on its own.
• You can also call it directly with /<skill name>. Before you make a new skill, run /skills to see the names already in use: if the new skill has the same name as one in another place, only one of them runs as /<name> (the name rules are in the next two sections).
• Keep scripts and reference documents in the same folder and point to them from SKILL.md. Keep SKILL.md short, under 500 lines.

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog or "what changed since the last tag".
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed.
4. Write plain sentences a user can understand. Skip internal refactors.

• Learn about agent skills — make, install, SONUB skills

Skills are an open standard — but Claude Code works its own way

Skills were first made by Anthropic, the company behind Claude, and released for free. Today they are an open standard called Agent Skills, managed at agentskills.io. Codex, Cursor, Gemini CLI, GitHub Copilot and many other AI tools read the same SKILL.md folder.

Be careful, though: the standard only defines what goes inside a skill folder. Where to look for skills and which one wins when names clash are left to each tool, and Claude Code works differently from what agentskills.io recommends. So a skill that works in another tool can behave differently in Claude Code.

• Folder: agentskills.io recommends .agents/skills/, which many tools share, but Claude Code reads .claude/skills/ (in the project) and ~/.claude/skills/ (personal). It does not read .agents/skills/.
• Same name: the common rule in the standard is that a project skill beats a personal one. In Claude Code it is the other way round — enterprise beats personal, and personal (~/.claude/skills/) beats project.
• Parent and child folders: the standard does not say. Claude Code reads the folder you start in and every parent up to the git repository root, and a child folder only when it works there (next section).
• Frontmatter: the standard has six fields — name, description, license, compatibility, metadata and allowed-tools. Claude Code adds more, such as disable-model-invocation, context: fork and paths. Other tools ignore them, and claude.ai uploads and the Skills API stop with an error.

For a skill you share with other AI tools, write the frontmatter with only the six standard fields. Then it loads unchanged in Claude Code and in the other tools.

Where Claude Code finds skills — your folder and its parents together

Claude Code reads .claude/skills/ in the folder where you start claude and in every parent folder up to the git repository root, and uses them all together — start in apps/web/ and the root skills are there too (in a git worktree it goes up only to the worktree root). A .claude/skills/ above the repository root is not read, so put skills for all your projects in ~/.claude/skills/.

• Skills in a folder below where you started are not read at first. They load the first time Claude reads or edits a file in that folder and stay until the session ends — until then they are not in the / menu. To load them early, run /add-dir with that folder.
• If the root and apps/web/ both have a skill named deploy, both stay available: /deploy runs the root one and /apps/web:deploy runs the one in apps/web/. Claude Code also lists both for Claude with an instruction to use the one whose folder holds the files it is working on, so the apps/web/ skill still applies to work there (official docs: Skills — skills that share a name).
• Plugin skills are separate, called as /<plugin-name>:<skill-name>, so they never clash with yours.

~/projects/                    ← above the repository root
├── .claude/skills/            ← not loaded (put shared skills in ~/.claude/skills/)
└── repo/                      ← git repository root
    ├── .claude/skills/        ← loaded
    └── apps/web/              ← run claude here
        ├── .claude/skills/    ← loaded (used together with the root)
        └── src/
            └── .claude/skills/  ← not at start — loads when Claude first reads or edits a file in src/

repo/
├── .claude/skills/deploy/SKILL.md            → /deploy
└── apps/web/.claude/skills/deploy/SKILL.md   → /apps/web:deploy

Run /skills to see which skills are loaded now. With many skills in parent and child folders, the descriptions of the least-used ones get cut first, so check now and then with /skill-doctor.

Subagents — hand off parts of the work

A subagent is a helper with its own context window, instructions and tools. Hand it a side job that would otherwise fill your conversation with search results, logs or file contents you will not need again — a big search, a code review, a test run. However many files it reads, only its summary comes back, so the main conversation stays short and focused on your task. It also gives you control: a subagent can be limited to certain tools (a reviewer that only reads), run on a faster, cheaper model and follow the same instructions every time. Make one when you keep asking for the same kind of helper.

• .claude/agents/<name>.md is for the project (commit it to share with the team), ~/.claude/agents/ is just for you. Only name and description are required.
• Limiting the tools it may use with tools is safer — let a reviewer only read.
• There are two ways it starts. ① You ask in your prompt: name it ("Review this change with the code-reviewer subagent"), or type @ and pick it to make sure that one runs. ② Claude hands work to it on its own: it compares your request with the description in the subagent's file, so write there what it does and when to use it — adding "use proactively" makes Claude delegate more readily.
• To make a new subagent, ask Claude to create one or write the file in the folder above yourself. Built-in ones such as Explore and Plan are there from the start.

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior reviewer.
Run `git diff` to see the changes, then report:
1. Bugs (with file and line)
2. Security problems
3. Missing tests
Do not edit files.

Hooks — commands that always run at set moments

CLAUDE.md is a request, so it can sometimes be forgotten, but a hook is a shell command Claude Code always runs at a set moment. Use hooks to run a formatter after a file edit, block dangerous commands or edits to secret files, and get a notification when work is done.

• PreToolUse — before a tool is used (can block it), PostToolUse — after a tool is used
• UserPromptSubmit — when you send a request, Stop — when Claude finishes its answer, SessionStart — when a session starts, Notification — when it needs your attention
• matcher chooses which tools the hook applies to (for example Edit|Write, Bash).
• What exit code 2 does depends on the event. On PreToolUse the action is blocked and the reason written to stderr is passed to Claude. On PostToolUse the tool has already run, so Claude only gets that reason as feedback.
• /hooks shows the hooks in place. The example below runs Prettier on every file Claude edits or writes: jq reads the file path from the hook input and npx prettier --write formats that file, so it needs jq and Node.js (npx).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Hooks run on your computer with your permissions. Add a hook from someone else only after you have read and understood its command.

MCP — connect outside tools

MCP (Model Context Protocol) is an open standard that lets AI tools use outside services (issue trackers, databases, browsers, document tools). Add an MCP server and Claude can use the tools that server provides.

• claude mcp add --transport http <name> <url> — add a remote server on the internet.
• claude mcp add <name> -- <command> — add a server that runs on your computer (stdio). Everything after -- goes to the server unchanged.
• Added with --scope project, it is saved in .mcp.json at the top of the repository and shared with the team (approval is asked on first use).
• /mcp shows the connection status and signs in (OAuth). claude mcp list shows the list.

# A remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that runs on your computer (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest

# Share it with the team — saved in .mcp.json
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

claude mcp list

• The full MCP guide — what MCP is, connecting servers and using them

Headless — scripts without the chat screen

claude -p "…" runs once without the chat screen, prints the result and exits. Use Claude as a building block in shell scripts, cron and CI.

• Pass input through a pipe (cat error.log | claude -p "…").
• --output-format json gives the result, session id and cost as JSON; stream-json sends progress line by line.
• --allowedTools sets the tools allowed for this run, and --max-turns the maximum number of turns.
• claude -p --continue continues the previous run, or --resume <session id> continues that session.

# One question, one answer
claude -p "Explain what src/auth.ts does in 5 lines"

# Pipe input in
cat build-error.log | claude -p "Find the cause and suggest a fix"

# JSON output for scripts (result, session_id, total_cost_usd)
claude -p "List the TODO comments in src/" --output-format json

# Limit what it may do and how long it runs
claude -p "Run the tests and fix failures" \
  --allowedTools "Read,Edit,Bash(npm test *)" --max-turns 10

In scripts, --bare starts fast without reading CLAUDE.md, hooks, plugins or MCP (the official docs say it will become the default for -p). Leave it out if you need the project instructions.

Advanced practice

1. Turn one job you do often (release notes, commit messages) into a skill in .claude/skills/ and call it with /skill-name.
2. Make a read-only code-reviewer subagent and have it review your current change.
3. Use a PostToolUse hook so a formatter or linter runs on every file edit.
4. Add one MCP server and check the connection with /mcp.
5. Write a one-line shell script that summarizes an error log with claude -p.

Done all five? Move on to the [Master] tab.

Official documentation

• Skills
• Subagents
• Hooks
• MCP
• Headless (-p)

Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.

Git worktrees — several sessions at once

When two sessions edit the same files in one folder, they overwrite each other. git worktree checks out the same repository into another folder on another branch, so you can run one Claude per folder and move several jobs forward at the same time.

• claude --worktree <name> (-w) creates a worktree and branch in .claude/worktrees/<name>/ and starts there. If you finish with no changes, it is removed automatically.
• Add .claude/worktrees/ to .gitignore, and list files Git ignores, such as .env, in .worktreeinclude to copy them into new worktrees.
• Each worktree may need its own dependency install (npm install and so on).
• Split work into independent jobs that touch different files, and merge them through PRs when done.

# Claude Code makes the worktree for you (.claude/worktrees/<name>/)
claude --worktree feature-login
claude -w bugfix-cart

# Or with plain git
git worktree add ../myapp-search -b feature-search
cd ../myapp-search && claude

git worktree list
git worktree remove ../myapp-search

GitHub Actions — @claude in issues and PRs

Install Claude Code GitHub Actions and just writing @claude in an issue or PR comment makes Claude read the repository, fix things and open a PR or leave a review. It runs on GitHub's runners, so your computer can be off.

1. Run /install-github-app in Claude Code in the terminal. It guides you through installing the GitHub app and adding the secret (ANTHROPIC_API_KEY or a token made with claude setup-token) — it needs gh and admin rights on the repository.
2. A workflow file like the one above appears in .github/workflows/.
3. Comment on an issue or PR, for example "@claude fix this bug".
4. A person reviews and tests the PR Claude opened before merging it.

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Claude in Actions also reads the repository's instruction file (AGENTS.md, or CLAUDE.md). The easiest way to make it follow your rules is a well-written instruction file.

Plugins and marketplaces — bundle and share a setup

A plugin bundles skills, subagents, hooks and MCP servers into one. A marketplace is a repository with a list of plugins. A team installs the same toolbox with one command and updates it together.

• /plugin — find, install, turn on and turn off plugins.
• Add a marketplace with /plugin marketplace add <owner/repo> and install with /plugin install <plugin>@<marketplace>.
• Only plugin.json goes in the plugin folder's .claude-plugin/. skills/, agents/ and hooks/ sit at the top of the folder. Test it with claude --plugin-dir ./my-plugin.
• If you only share skills, npx skills add works too — that is how SONUB skills are shared.

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← name, description, version
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

/plugin marketplace add my-team/claude-plugins
/plugin install my-plugin@claude-plugins
/plugin

• Install SONUB agent skills

Running a team setup — so rules stay clear as they pile up

When many people and many AIs work in one repository, settings pile up fast. Decide what is shared and what is personal, and what is a request and what is enforced.

• Shared (commit): AGENTS.md, .claude/settings.json, .claude/skills/, .claude/agents/, .mcp.json (and every folder's CLAUDE.md if you use CLAUDE.md)
• Personal (do not commit): .claude/settings.local.json, ~/.claude/ — keep personal instructions in ~/.claude/CLAUDE.md (do not put a CLAUDE.local.md in the project, because it stops AGENTS.md)
• Keep instruction files short. Add a rule only when the same mistake repeats, and delete rules that are wrong or no longer useful.
• Enforce what must be followed with permissions (deny) and hooks, not with instructions.
• Push company-wide rules down through managed settings — other settings cannot override them.

Long tasks — check its own work until it is done

A master gives Claude a "definition of done" and has it check that definition itself. With a test a machine can judge — tests, lint, a build — it can work for a long time without anyone watching.

• Give the definition of done as commands — "until npm test and npm run lint both pass".
• Have it write what is done and what is left in a file such as PROGRESS.md, so it can carry on even after the context is summarized or the session changes.
• Have it commit after each complete, working step that can stand on its own, so you can roll back that step independently. Do not split one unfinished change across several commits that must be undone together.
• If three attempts to solve the same problem fail, have Claude stop and write down what it tried, why those attempts failed and what is blocking progress, before it tries again. This stops loops that go nowhere.
• When it is all done, hand a cross-review to another AI (for example codex review) or a subagent.

• Goal and Ralph Loop: let an agent keep going until it is really done
• VPS and tmux: keep an agent working 24 hours a day

Master practice — several sessions and automation

1. Make a second working folder with git worktree add ../my-project-b -b try-b, run claude in each folder and give each a different small job. If git status changes separately in the two folders, it worked.
2. Make a one-line review command: git diff | claude -p "List bugs in this diff". Put in a bug on purpose and check that it finds it.
3. Write one team rule (for example, run the tests before committing) in AGENTS.md and also enforce it with a hook. Break the rule on purpose and check that the hook stops it.
4. Bundle one of your skills and one subagent into a plugin as in the plugins section above, install it, and check that it loads in another project too.
5. Give a long task with a finish line written as a command (for example, npm test passes). When it says it is done, check the diff and the test result yourself.

If you get stuck: list worktrees with git worktree list and remove one with git worktree remove. If a hook blocks too much, take it out of settings.json for a moment and check with /hooks. Done all five? Check yourself with the checklist below.

Master checklist — the whole path from Basics to Master

• Basics — you run claude in a Git project folder, plan first with /plan, approve only what belongs to the job and check git status and git diff before you commit
• Intermediate — for web work the browser connection is on, so Claude opens and checks the page it changed
• Intermediate — only AGENTS.md in the project, so every AI works from the same instructions. If you use CLAUDE.md, every folder that has an AGENTS.md also has a CLAUDE.md that references it with the line @AGENTS.md on its own
• Intermediate — permission rules let safe commands run without asking and block secret files with deny
• Intermediate — you watch the context with /context, shrink it with /compact and use /clear when you switch to a new, unrelated task; each request says where, what and how to check
• Advanced — repeated jobs go to skills (check the names in use with /skills first), big searches and reviews to subagents
• Advanced — what must be followed is enforced with hooks and permissions, outside tools come in through MCP servers you trust, and one-off jobs run in scripts with claude -p
• Master — parallel work runs in worktrees, and @claude in GitHub Actions takes on issues and PRs
• Master — the team's skills, subagents, hooks and MCP servers are shared as one plugin, and shared and personal settings are kept apart
• Master — you give the definition of done as commands, commit each complete working step and check the result yourself with the diff and tests

The tools change often. Keep up with new features through /claude-skill update in the claude-skill skill or the official change log (CHANGELOG).

Official documentation

• Worktrees
• GitHub Actions
• Plugins
• Settings

Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.