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.

It can show a plan before it changes anything, and it asks before editing files or running commands — you decide what it may do (permissions). Rules for your project go in CLAUDE.md, which it reads at the start of every session.

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, move into your project folder with cd <folder>, 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. Ask “What is in this project?” so it reads the project.
3. Run /init to create CLAUDE.md, then add your test command and the rules to follow.
4. Press Shift+Tab to switch to plan mode and ask for a change. Read the plan, fix it, then approve it.
5. Read what changed with git diff, run the tests yourself, then commit.

Basic practice — try it once from the start

1. Make a practice folder (mkdir hello-ai && cd hello-ai), turn it into a Git repository with git init, then run claude. If you see the input box, it worked.
2. Ask: "Make index.html, a one-page website that shows today's date." If it asks before creating the file, read what it plans and allow it.
3. Open index.html in your browser and check with your own eyes that the date shows.
4. See what changed with git status, then save it with git add . and git commit -m "first page".
5. Ask once more: "Make the date bigger." If you do not like the result, go back to the last commit with git restore index.html.

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). But if even one exists, AGENTS.md is not read
• 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

# 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).
• An AGENTS.md in a subfolder is read only when Claude opens a file there with the Read tool. When it writes a new file straight into that folder, it may not know the rules yet. A subfolder CLAUDE.md is read on reads, writes and edits.
• 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. ① With AGENTS.md only, a subfolder's AGENTS.md is read when Claude opens a file there with Read. ② 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 fresh conversation when you begin unrelated work.
• 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 — SONUB rule: auto compact at about 400k, base context at 6% or less

Claude rereads the whole current context every time you ask for something, so the bigger the context, the more tokens each request costs. Use auto compact to work with about 400k tokens instead of the full 1M, and keep the base context that is taken before the conversation even starts (the default system prompt, skills, MCP and so on) at 6% or less. Doing this cuts your usage a lot. About 400k and 6% are SONUB’s own rule of thumb, not official recommendations — the official docs only describe the settings.

• /autocompact 444k — compacts automatically when the context reaches 444k tokens. It is saved in your user settings for the current model; /autocompact auto undoes it.
• For every model, put "autoCompactWindow": 444000 in ~/.claude/settings.json (example below). For one launch only, start with claude --autocompact 444k.
• Run /context right after opening a new conversation. What is already taken before you ask anything — system prompt, system tools, MCP tools, skills, memory files (CLAUDE.md · AGENTS.md) — is the base context, and together it should be 6% or less.
• Over 6%? Trim it — turn off MCP servers you do not use in /mcp, remove unused skills and plugins, and keep only the rules you really need in CLAUDE.md · AGENTS.md.

{
  "autoCompactWindow": 444000
}

The base context is sent with every request, so saving even a few percent adds up over the whole conversation and cuts usage a lot. Even before it compacts, starting fresh with /clear when the job changes is the biggest saving.

• Tool context — about 400k instead of 1M

Asking well — where, what and how to check

A good request has three parts: where (files and folders), what (the behaviour you want) and how to check it (tests, commands, screens). The clearer the three are, the less Claude wanders and the more it checks its own results.

• 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, start with "Read first and show me only a plan — do not change anything yet", or enter plan mode with /plan.
• 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 clear the context between tasks. 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 AGENTS.md at the top of your project 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? Move on 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>, and /skills shows the list.
• 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

If the folder you are in has a .claude/skills folder and a parent folder has one too, Claude Code uses the skills in both together. It only goes up as far as the git repository root.

• It reads .claude/skills/ in the folder where you start claude and in every parent folder up to the repository root. Start in apps/web/ and the root skills are there too.
• A .claude/skills/ above the repository root is not read. Put skills for all your projects in ~/.claude/skills/. In a git worktree it goes up only to the worktree root.
• 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 can be used: /deploy runs the root one and /apps/web:deploy runs the one in the child folder. Claude is told to use the skill of the folder that holds the files it is working on.
• 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. Give it a big search or review: however many files it reads, only the result comes back to the main conversation, which stays clean.

• .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.
• Call it like "Review this change with the code-reviewer subagent", or Claude hands work to it on its own when the description fits.
• 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).
• If the hook command ends with exit code 2, the action is blocked and the reason written to stderr is passed to Claude.
• /hooks shows the hooks in place. The example above tidies every edited file with Prettier (it needs jq).

{
  "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

Add only MCP servers you trust. A server that fetches outside text can bring in instructions hidden in that text (prompt injection).

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 small step, so you can roll back at any time.
• Have it stop and write down why after three failed tries, to prevent 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

• Only AGENTS.md in the project — every AI works from the same instructions (if you use CLAUDE.md, put one in every folder with the one line @AGENTS.md)
• Permission rules let safe commands run without asking and block secret files with deny
• Repeated jobs go to skills, big searches and reviews to subagents
• What must be followed is enforced with hooks
• Parallel work runs in worktrees; repeated work is automated with claude -p and GitHub Actions
• You give the definition of done as commands 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.