Quick Start

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 to import what you already have into one source in a single step.

New project

1. Scaffold the canonical directory

   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)

   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.

2. Edit your root rule

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

   Example root rule:

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

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

4. Generate

   agentsmesh generate

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

Existing project with tool configs

1. Initialize

   agentsmesh init

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

   To skip the wizard and auto-import everything:

   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

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

3. Generate for all targets

   agentsmesh generate

4. Verify nothing unexpected changed

   agentsmesh diff

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

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.

Optional: teach your agents

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.

Try a community skill pack

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 for the full prompt walkthrough, --force behavior, and JSON shape; see agentsmesh install, agentsmesh uninstall, and agentsmesh 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.

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.

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, commands, agents, and skills
• Teach your agents with lessons — a shared memory that learns from failures
• Set up CI drift detection
• Share config across repositories with extends
• Browse the full CLI reference