ai-config

name	ai-config
description	Use when working with .ai/ directory files, aisync.toml, or AI tool configuration. Teaches the canonical format, conditional tags, and sync relationships.
version	1.0.0

AI Configuration with AgentSync

Canonical Source of Truth

The .ai/ directory is the single source of truth for all AI tool configurations. Never edit synced copies directly — always edit files in .ai/ and then sync.

File Purposes

File	Purpose
.ai/instructions.md	Main project instructions. Synced to CLAUDE.md, AGENTS.md, and .cursor/rules/project.mdc.
.ai/hooks.toml	Event hook definitions (pre/post tool use, shell execution, etc.).
.ai/mcp.toml	MCP (Model Context Protocol) server definitions.
.ai/plugins.toml	Plugin references and configuration.
aisync.toml	AgentSync configuration — controls sync strategy per tool (symlink, copy, generate). Lives at project root.

Subdirectories

Directory	Purpose
.ai/memory/	Context files providing persistent knowledge across sessions.
.ai/rules/	Coding rules with YAML frontmatter (style, conventions, patterns).
.ai/commands/	Slash command definitions for AI tools.
.ai/skills/	Skill modules that teach AI tools domain-specific knowledge.
.ai/agents/	Agent definitions for multi-agent workflows.

Conditional Tags

Use conditional tags to include content only for specific tools:

<!-- aisync:claude-only -->
This content only appears in Claude Code output.
<!-- /aisync:claude-only -->

<!-- aisync:cursor-only -->
This content only appears in Cursor output.
<!-- /aisync:cursor-only -->

<!-- aisync:opencode-only -->
This content only appears in OpenCode output.
<!-- /aisync:opencode-only -->

Content outside conditional tags is included in all tool outputs.

Critical Rules

1. Always edit canonical .ai/ files. Never edit synced copies directly. The following are generated outputs and will be overwritten on sync:

   • CLAUDE.md
   • .cursor/rules/project.mdc
   • AGENTS.md

2. Run aisync sync (or /aisync:sync) after making changes to propagate updates to all configured tools.

3. Check sync state with aisync status (or /aisync:status) to see if tool-native files have drifted from canonical content.

Sync Strategies

The aisync.toml file controls how each tool receives its configuration:

• symlink — Tool-native file is a symlink to the canonical file (fast, always in sync).
• copy — Canonical content is copied to the tool-native location (for tools that don't support symlinks).
• generate — Content is transformed/generated from canonical format to tool-native format (e.g., adding frontmatter for .mdc files).