---
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.

## 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))

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
   ```

   AgentsMesh scans for existing configs from every [supported AI coding tool](/reference/supported-tools/) and prompts you to import each one found.

   To auto-import everything without prompts:

   ```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>

## 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/)
- Set up [CI drift detection](../guides/ci-drift-detection/)
- [Share config across repositories](../guides/sharing-config/) with `extends`
- Browse the full [CLI reference](../cli/)
