A beginner-friendly guide to setting up a clean, maintainable, and secure Claude Code workspace.

1. Project Structure
2. AGENTS.md / CLAUDE.md
3. Symlinks Explained
4. Adding Skills
5. Security & Prompt Injection
6. Managing Your Plans

A well-organized Claude Code setup uses a central .agents/ folder as the single source of truth, then links it to where Claude Code expects things (.claude/). You only ever edit files in .agents/.

your-project/
├── CLAUDE.md          → symlink to AGENTS.md  (Claude Code reads this automatically)
├── AGENTS.md          ← the real file you edit
│
├── .agents/           ← your single source of truth
│   ├── skills/        ← reusable AI skill definitions
│   ├── commands/      ← custom slash commands
│   ├── rules/         ← behavior rules for Claude
│   └── hooks/         ← event-triggered scripts
│
├── .claude/           ← where Claude Code looks for config
│   ├── skills/        → symlink to .agents/skills/
│   ├── commands/      → symlink to .agents/commands/
│   ├── rules/         → symlink to .agents/rules/
│   └── hooks/         → symlink to .agents/hooks/
│
└── .plans/            ← your project plans (optional but recommended)
    └── ROADMAP.md

Why two folders? Claude Code looks in .claude/ for config. You keep real files in .agents/ and point .claude/ to them with symlinks. Edit only .agents/ — changes appear automatically in .claude/.

CLAUDE.md is the most important file in your setup. Claude Code reads it automatically every time it starts. Since CLAUDE.md is a symlink to AGENTS.md, you only ever edit AGENTS.md.

Use it to tell Claude about your project, your preferences, coding standards, and anything it should always know.

# Project: my-app

## Stack
- Language: C / Python
- Build: Makefile

## Conventions
- 4-space indentation, no tabs
- Snake_case for variables
- All public functions must have docstrings

## Key Commands
- `make`       — build the project
- `make test`  — run tests
- `make clean` — clean build artifacts

## Plans
- See `.plans/ROADMAP.md` for current priorities

Symlinks let a file or folder "point" to another location. Editing the real file updates both places instantly.

# At the root of your project:

# 1. Create AGENTS.md
touch AGENTS.md

# 2. CLAUDE.md → AGENTS.md
ln -s AGENTS.md CLAUDE.md

# 3. .claude/ subfolders → .agents/ subfolders
mkdir -p .agents/skills .agents/commands .agents/rules .agents/hooks
mkdir -p .claude

ln -s ../.agents/skills    .claude/skills
ln -s ../.agents/commands  .claude/commands
ln -s ../.agents/rules     .claude/rules
ln -s ../.agents/hooks     .claude/hooks

After this, only edit files inside .agents/ — never touch .claude/ directly.

Skills are reusable instructions that extend what Claude can do in your project (generate docs, follow a specific workflow, run audits, etc.).

Browse and search the community skills registry at skills.sh.

/find-skill "describe what you need"

Try different keywords if the first search doesn't give good results. The command searches the registry for you.

/create-skill

This walks you through the process of defining a new skill from scratch and saving it into .agents/skills/.

Once you find or create a skill, place it in .agents/skills/. It will be available via .claude/skills/ automatically through the symlink.

⚠️ This is the most important section for your safety.

Skills downloaded from the internet can contain malicious hidden instructions — this is called a prompt injection attack. A bad actor embeds instructions inside a skill file that silently alter Claude's behavior: leaking your code, deleting files, or doing things you never asked for.

Before installing any skill, read it carefully and look for:

• Instructions hidden in comments or whitespace
• Commands that seem unrelated to what the skill claims to do
• References to external URLs or APIs you didn't expect
• Anything that asks Claude to "ignore previous instructions"

1. Download / find the skill
2. Open the skill file and read every line
3. Look for anything unexpected or suspicious
4. Only then move it into .agents/skills/

Use /find-skill as a starting point, but always audit manually before using. The few minutes it takes can protect your entire project.

Claude Code does not automatically read PLAN.md or your .plans/ folder. You must explicitly tell it about them in AGENTS.md.

Create a PLAN.md at the root and reference it in AGENTS.md:

## Plans
- See `PLAN.md` for the current project roadmap

Create a .plans/ folder at the root and reference it:

.plans/
├── ROADMAP.md
├── SPRINT-1.md
└── ARCHITECTURE.md

Then in AGENTS.md:

## Plans
- See `.plans/ROADMAP.md` for the overall roadmap
- See `.plans/SPRINT-1.md` for current sprint tasks

If you forget to add it to AGENTS.md, you can point Claude to it during a session:

Read PLAN.md before we start

or using the @ syntax:

@PLAN.md what should we work on next?

Since CLAUDE.md is a symlink to AGENTS.md, adding references there is all you need — no need to edit anything in .claude/.