---
draft: false
title: Quick Start
description: Get AgentsMesh running in under 5 minutes — scaffold a new canonical config directory or import your existing AI tool configs.
sidebar:
  order: 2
---

import { Steps, Aside, Tabs, TabItem } from '@astrojs/starlight/components';

Choose the path that matches your situation. Most repos already use at least one AI tool — if yours does, start with **[Existing project with tool configs](#existing-project-with-tool-configs)** to import what you already have into one source in a single step.

## New project

<Steps>

1. **Scaffold the canonical directory**

   ```bash
   agentsmesh init
   ```

   This creates:
   - `agentsmesh.yaml` — project configuration
   - `agentsmesh.local.yaml` — local overrides (gitignored)
   - `.agentsmesh/rules/_root.md` — starter root rule
   - Updates `.gitignore` to exclude `agentsmesh.local.yaml`, `.agentsmeshcache`, `.agentsmesh/.lock.tmp`, and `.agentsmesh/packs/` (see [What to commit](#what-to-commit-and-what-to-gitignore))

   <Aside type="tip">
     On an interactive terminal, `agentsmesh init` asks which tools to target and whether to enable lessons. In CI or with `--yes` it runs non-interactively with sensible defaults.
   </Aside>

2. **Edit your root rule**

   ```bash
   # Open the root rule in your editor
   vi .agentsmesh/rules/_root.md
   ```

   Example root rule:

   ```markdown
   ---
   root: true
   ---

   # Project Guidelines

   - Write tests before implementation.
   - Max 200 lines per file.
   - Use TypeScript strict mode.
   - Prefer pure functions over classes.
   ```

3. **Configure your targets**

   Open `agentsmesh.yaml` and set the tools your team uses:

   ```yaml
   version: 1
   targets:
     - claude-code
     - cursor
   features:
     - rules
     - commands
     - mcp
   ```

4. **Generate**

   ```bash
   agentsmesh generate
   ```

   Output files are written to each tool's native directory (`.claude/`, `.cursor/`, etc.).

</Steps>

## Existing project with tool configs

<Steps>

1. **Initialize**

   ```bash
   agentsmesh init
   ```

   On a terminal this launches a short [wizard](../../cli/init/#interactive-wizard) — pick which tools to target, then (if existing configs from any [supported AI coding tool](../../reference/supported-tools/) are detected) choose whether to import them, and in a project toggle lessons.

   To skip the wizard and auto-import everything:

   ```bash
   agentsmesh init --yes
   ```

   That imports native configs into `.agentsmesh/` and still drops example `commands/`, `agents/`, and `skills/` stubs anywhere import did not already create files in those areas.

2. **Review the canonical files**

   ```bash
   ls .agentsmesh/rules/
   ls .agentsmesh/commands/
   cat .agentsmesh/permissions.yaml
   ```

3. **Generate for all targets**

   ```bash
   agentsmesh generate
   ```

4. **Verify nothing unexpected changed**

   ```bash
   agentsmesh diff
   ```

   If the diff looks clean, commit both `.agentsmesh/` and the generated files.

</Steps>

<Aside type="tip">
  After init, `.agentsmesh/` is the only thing you should edit. Generated files in `.claude/`, `.cursor/`, etc. are artifacts — regenerate them, don't edit them directly.
</Aside>

## Optional: teach your agents

```bash
agentsmesh init --lessons
agentsmesh generate
```

This adds a shared memory your agents read before edits and write after failures, so the same mistake doesn't happen twice — in any tool. It also gitignores `.agentsmesh/lessons/recall-log.jsonl` (opt-in telemetry, a runtime artifact). See [Teach your AI agents with lessons](../../guides/lessons/).

## Try a community skill pack

```bash
agentsmesh install github:addyosmani/agent-skills    # auto-detects the layout
agentsmesh installs list                              # see what landed
agentsmesh uninstall addyosmani-agent-skills          # remove cleanly when done
```

The classifier sees `skills/<kebab>/SKILL.md`, multi-tool root rules, and per-target `.claude/commands` / `.gemini/commands` directories, and imports the whole pack in one shot. Per-entity prompts only surface when there are out-of-scope relative links to resolve. See the [skill-pack guide](../../guides/installing-skill-packs/) for the full prompt walkthrough, `--force` behavior, and JSON shape; see [`agentsmesh install`](../../cli/install/), [`agentsmesh uninstall`](../../cli/uninstall/), and [`agentsmesh installs`](../../cli/installs/) for flag references.

## What to commit and what to gitignore

`agentsmesh init` writes the recommended `.gitignore` entries. The defaults are deliberate:

| Path | In git? | Why |
|---|---|---|
| `.agentsmesh/` (canonical) | **commit** | The source of truth — must be in git. |
| `.agentsmesh/.lock` | **commit** | Drift detection contract. `agentsmesh check` compares against this. |
| `.agentsmesh/packs/` | **gitignore** | Materialized from `installs.yaml`. Same model as `node_modules` — `agentsmesh install --sync` reproduces them deterministically post-clone. |
| `agentsmesh.local.yaml` | **gitignore** | Per-developer overrides. |
| `.agentsmesh/.lock.tmp` | **gitignore** | Transient. |
| `.agentsmeshcache` | **gitignore** | Remote-extends cache. |
| Generated tool folders (`.claude/`, `.cursor/`, `.github/`, `.gemini/`, `CLAUDE.md`, `AGENTS.md`, etc.) | **commit** | AI tools read these at runtime. Committing means a fresh clone has working AI configs without a build step. `agentsmesh check` in CI catches drift. |

<Aside type="note">
  Why generated configs stay committed: same reason `package-lock.json` does. They're deterministic build output that downstream consumers (in this case, the AI tool itself) read directly. Gitignoring them breaks fresh-clone UX and makes `agentsmesh check` meaningless. PR reviewers also benefit from seeing the projected diff in the format Claude/Cursor/Copilot will actually consume.
</Aside>

If your team has a strong reason to gitignore generated configs (monorepo size, regenerate-on-checkout hooks), add the target-specific entries manually — but expect to wire `agentsmesh generate` into your post-checkout flow.

## What's next

- Add [rules](../../canonical-config/rules/), [commands](../../canonical-config/commands/), [agents](../../canonical-config/agents/), and [skills](../../canonical-config/skills/)
- [Teach your agents with lessons](../../guides/lessons/) — a shared memory that learns from failures
- Set up [CI drift detection](../../guides/ci-drift-detection/)
- [Share config across repositories](../../guides/sharing-config/) with `extends`
- Browse the full [CLI reference](../../cli/)
