Agsync

agsync

You are an expert in agsync, a Git-native CLI tool that compiles and syncs skill definitions, commands, and MCP tool bindings across multiple AI coding agents.

Important

Never edit files outside .agsync/ directly. All generated output (AGENTS.md, .agents/skills/, .agents/commands/, agent-specific symlinks) is managed by agsync. Edit sources in .agsync/ and run agsync sync to regenerate.

What agsync Does

agsync reads canonical definitions from .agsync/ and generates agent-specific output. The .agsync/ directory is the single source of truth.

Project Structure

project/
├── agsync.yaml                          # Root config (one per repo)
├── .agsync/                             # Root definitions
│   ├── instructions.md                  # User-written project instructions
│   ├── skills/                          # Skill definitions
│   │   ├── my-skill/
│   │   │   ├── SKILL.md                 # Skill definition (frontmatter + body)
│   │   │   ├── scripts/                 # Optional executable code
│   │   │   ├── references/              # Optional documentation
│   │   │   └── assets/                  # Optional templates, resources
│   │   └── imported-skill/
│   │       └── SKILL.md                 # Stub with source (content fetched on sync)
│   ├── commands/                        # Slash commands (.md files)
│   │   └── deploy.md                    # /deploy command
│   └── mcp/*.yaml                       # MCP server definitions
│
├── frontend/                            # Subfolder with its own .agsync/
│   ├── .agsync/
│   │   ├── instructions.md              # Subfolder instructions
│   │   └── skills/ui-kit/SKILL.md       # Scoped skill
│   └── AGENTS.md                        # Generated (scoped instructions)
│
│  ─── Generated output (do not edit) ───
├── AGENTS.md                            # Root instructions + skill listing + scope refs
├── .agents/skills/*/SKILL.md            # Canonical skill output
├── .agents/skills/frontend--ui-kit/     # Scoped skill (double-dash)
├── .agents/commands/*.md                # Canonical command output
│
│  ─── Agent symlinks (root only, do not edit) ───
├── CLAUDE.md → AGENTS.md               # Symlink
├── .claude/skills/ → .agents/skills/    # Symlink
├── .cursor/skills/ → .agents/skills/    # Symlink
├── .mcp.json                            # Generated MCP config (Claude)
├── .cursor/mcp.json                     # Generated MCP config
└── .codex/config.toml                   # Generated MCP config (TOML)

Skill Definition (SKILL.md)

Each skill is a directory under .agsync/skills/ with a SKILL.md file:

---
name: my-skill
description: What this skill does and when to use it
---

Detailed instructions for the agent.

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | name | Yes | Skill identifier, must match the directory name | | description | Yes | What the skill does and when to use it | | source | No | Remote skill reference (content fetched during sync) | | extends | No | List of skills to inherit from (local or GitHub) | | tools | No | List of tool names this skill can use |

A skill must have either body instructions or source (or both).

Imported Skill (stub with source)

---
name: code-reviewer
description: Reviews code for quality
source:
  registry: github
  org: Shubhamsaboo
  repo: awesome-llm-apps
  path: awesome_agent_skills/code-reviewer
  version: "v1.0.0"
---

Version Locking

External skills are pinned to exact versions via source.version. A lock file (agsync-lock.yaml) records the resolved commit/version and content hash for each external dependency.

Use --frozen with sync or plan in CI to enforce the lock file — the command fails if the lock is missing or stale.

MCP Namespaces

Tag MCP servers with one or more namespaces (e.g. ci-cd, coding-agents) and filter at sync time. Useful when CI runners and local coding agents need different sets of servers.

# .agsync/mcp/github-actions.yaml
name: github-actions
description: GitHub Actions MCP server
namespaces: [ci-cd]
command: npx
args: ["-y", "@modelcontextprotocol/server-github-actions"]

Filter at sync time:

agsync sync --namespace ci-cd          # only ci-cd-tagged + untagged servers
agsync sync --namespace coding-agents  # only coding-agents-tagged + untagged servers
agsync sync                            # all servers (no filter)

Rules:

• namespaces is optional. MCPs without it (or with an empty array) are always included (treat as global).
• A skill that references an MCP excluded by the active namespace produces a warning, not an error.
• Scaffold a tagged MCP with agsync mcp add --namespace ci-cd (repeat the flag to add multiple).

Commands

Commands are .md files under .agsync/commands/. The filename becomes the slash command name.

.agsync/commands/deploy.md    → /deploy
.agsync/commands/review.md    → /review

CLI Commands

| Command | Description | |---------|-------------| | agsync init | Scaffold a new project | | agsync skill add | Create a local empty skill | | agsync skill add github: | Import a skill from GitHub | | agsync skill add clawhub: | Import a skill from ClawHub | | agsync skill remove | Remove a skill | | agsync command add | Create a new command (.md) | | agsync command remove | Remove a command | | agsync mcp add [--namespace ] | Create a new tool definition (.yaml), optionally tagged | | agsync mcp remove | Remove a tool | | agsync validate | Validate config and definitions | | agsync plan [--frozen] [--namespace ] | Preview changes without writing | | agsync sync [--frozen] [--namespace ] | Resolve skills, fetch sources, generate agent configs | | agsync doctor | Check environment health | | agsync version | Show version and check for updates | | agsync update | Update to latest version |

All add and remove commands resolve the nearest .agsync/ directory upwards in the directory tree, so they work correctly from any subdirectory (e.g. running from frontend/ adds to frontend/.agsync/).

agsync.yaml Format

version: "1"
skills:
  - path: .agsync/skills/*
commands:
  - path: .agsync/commands/*
tools:
  - path: .agsync/mcp/*.yaml
agents:
  claude:
    instructions: { enabled: true }
    skills: { enabled: true }
    commands: { enabled: true }
    mcp: { enabled: true }
  cursor:
    skills: { enabled: true }
    mcp: { enabled: true }
  codex:
    instructions: { enabled: true }
    skills: { enabled: true }
    mcp: { enabled: true }

Generated Output

• AGENTS.md is generated from .agsync/instructions.md + skill listing + scope cross-references. Agent-specific instruction files (CLAUDE.md, GEMINI.md, etc.) are symlinks to AGENTS.md, created only at the repo root.
• Subfolders with .agsync/instructions.md or skills get their own AGENTS.md generated in-place (e.g. frontend/AGENTS.md). The root AGENTS.md references these: "When working in folder: frontend — you MUST load frontend/AGENTS.md".
• .agents/skills/ and .agents/commands/ contain the canonical output with "managed by agsync" headers. Scoped items use double-dash directory names (e.g. frontend--ui-kit).
• Agent skill/command directories (.claude/skills/, .cursor/skills/, etc.) are symlinks to .agents/skills/ and .agents/commands/.
• MCP configs are generated per-agent (JSON or TOML), merged with existing entries.

Supported Agents

claude, cursor, codex, windsurf, copilot, gemini, opencode, antigravity

Examples

See the reference files for detailed examples:

• references/simple-skill.md — minimal skill definition
• references/skill-with-resources.md — skill with scripts, references, assets
• references/importing-skills.md — importing from open source
• references/extending-skills.md — extending via source or extends
• references/mcp-tool-definition.md — MCP tool with env expansion

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yiftahb
• Source: yiftahb/agsync
• License: MIT

Install and usage instructions live in the source repository linked above.