In a team environment, it's unrealistic to standardize on a single AI coding tool. Some engineers prefer Cursor, others work in Claude Code. Forcing one choice usually reduces productivity rather than improving it.

The real problem appears when people switch tools.

In our case, we have a single monorepo containing architecture documentation, a Next.js application, and CLI tooling. We also rely heavily on project-specific AI instructions: conventions for ADRs, OpenAPI documentation standards, repository structure, and common commands.

Originally, this context was split across tool-specific locations:

  • CLAUDE.md
  • Cursor project configuration
  • .claude/skills/
  • .cursor/skills/

As long as engineers stayed within one tool, everything worked. The moment someone switched, the AI agent lost awareness of our conventions. The knowledge still existed in the repository, but not in a place visible to the new agent.

Each switch effectively reset AI productivity.

We did not want to:

  • lock the team into a single tool,
  • maintain duplicated skill definitions,
  • or continuously reconfigure context per IDE.

Instead, we introduced a single source of truth for AI skills and project context.

Architectural principle: one canonical location

The core decision was simple: define one canonical folder for skills and make every agent read from it.

We created a skills/ directory at the repository root. This folder contains all project-specific skills:

skills/
├── adr-creator/
│   └── SKILL.md
├── openapi-spec/
│   └── SKILL.md

Each skill is a subdirectory with a SKILL.md file containing frontmatter (name, description) and structured instructions.

This directory is the only place where skills are edited. It is versioned like any other part of the codebase.

We explicitly avoided using .claude/skills/ or .cursor/skills/ as primary locations. Tool-specific directories should not be the source of truth.

Making tools converge: symlinks

Claude Code expects skills under .claude/skills/. Cursor expects .cursor/skills/.

Instead of duplicating content, we created symbolic links:

.claude/skills  → ../skills
.cursor/skills  → ../skills

Both tools now resolve to the same physical directory. Updating a skill updates behavior in both agents.

The symlinks are committed to the repository so that a standard clone on macOS, Linux, or WSL preserves the structure. For Windows environments where symlinks may not be available, we document a one-time manual copy as a fallback.

Unifying high-level context

Beyond skills, we also maintain high-level project context: repository structure, conventions, common commands.

We store this in AGENTS.md.

Claude Code expects a CLAUDE.md file, so instead of maintaining two copies, we created another symlink:

CLAUDE.md → AGENTS.md

This eliminates divergence between tool-specific documentation files. There is exactly one context document.

Compatibility with skills.sh and .agents/skills/

The skills.sh CLI and several agents rely on .agents/skills/ as a standard location. By default, npx skills add installs skills into ./skills/, which aligns with our canonical directory.

To ensure compatibility with agents that only read from .agents/skills/, we added:

.agents/skills → ../skills

As a result:

  • Custom internal skills
  • Community skills installed via npx skills add
  • Cursor
  • Claude Code
  • Any agent that respects .agents/skills/

All operate on the same directory.

We ignore the rest of .claude/, .cursor/, and .agents/ in .gitignore, but explicitly keep the skills symlinks tracked.

Operational workflow

Adding a new internal skill:

  1. Create skills/<skill-name>/SKILL.md
  2. Commit

No additional configuration is required.

If we want to import a community skill:

npx skills add owner/repo --skill skill-name

The skill is installed into skills/, immediately visible to all agents.

Outcome

This structure achieves several goals:

  • Switching between Cursor and Claude Code does not reset AI context.
  • There is a single update point for skills and conventions.
  • Onboarding is simplified: cloning the repository is enough.
  • The team is not locked into a single AI tool.
  • Community skills can be integrated without structural changes.

From an architectural perspective, the key decision was to treat AI skills as versioned project artifacts rather than tool configuration. Once that shift is made, the rest becomes a matter of directory structure and indirection.

The pattern is simple: define one canonical location, and make every tool resolve to it.

The result is stable AI productivity regardless of which coding agent an engineer chooses.