Managing AI agent skills at scale: a three-repo architecture

Five days after releasing 22 open-source Synthesis Skills, I noticed a gap in the tooling. My synthesis-daily-rituals skill — a morning checklist I refine almost daily — existed in two places: the installed copy in ~/.claude/skills/ and the source copy in a git repo. Both had improved independently over the week. The installed copy had new steps for Slack MCP authentication and better handling for long threads. The source had a restructured evening checklist and a dependency validation step.

My shell installer handled drift by warning and then overwriting the installed copy. That was the wrong behavior for a skill whose methodology had improved through use. The installed copy wasn't stale. It was ahead in some areas and behind in others. What I needed was a merge — one that understood both sets of changes were additive and compatible.

The Agent Skills standard defines a portable format: SKILL.md, YAML frontmatter and progressive disclosure, already usable across forty-plus tools. I needed a management layer around that format. What happens when you have 35 skills from three different sources with three different access levels? What happens when installed copies and source copies diverge? What prevents a private skill from depending on a team skill your colleague doesn't have?

Update (July 30, 2026): The public repository (now at github.com/synthesisengineering/synthesis-skills) ships as a single-source dual-runtime plugin for Claude Code and OpenAI Codex — 49 public skills as of v4.7.0, plugin-first install with direct copies as the fallback. The three-repo boundaries, provenance metadata, and dependency hierarchy described here still apply.

Three repos, strict boundaries

The model separates three repositories by access level and gives each collection a clear dependency policy.

Public — 23 open-source skills. Code review, content quality, project management, thinking frameworks. CC0 and Apache 2.0. Installed globally to ~/.claude/skills/.

Private — 13 skills containing personal workflows, client-specific publishing processes, social media strategies with account details and timing preferences. Same global install location, but the source repo is private.

Shared — Team-level skills that encode institutional knowledge. How this team releases software, how this team verifies cherry-picks. Installed at the project level (.claude/skills/ within a project directory) rather than globally, because team conventions are project-scoped.

The dependency hierarchy: public depends on public only. Private depends on public and private. Shared depends on public and shared. No cross-collection dependencies between private and shared.

This prevents a specific failure mode I've seen in plugin ecosystems: your setup works because you have all the pieces, but a colleague's breaks silently because their collection is different. A private skill depending on a shared skill breaks when you leave that team. A shared skill depending on a private skill fails for every team member except you. The hierarchy forces methodology to live at the right layer — and forces promotions from private to shared to public to be deliberate decisions.

Provenance

The copy-based installer writes a .source.json file for each skill. For example:

{
  "source_repo": "github.com/rajivpant/synthesis-skills",
  "source_type": "public",
  "source_path": "synthesis-thinking-framework/SKILL.md",
  "source_commit": "af6a447",
  "installed_at": "2026-03-23T21:30:00Z",
  "installed_by": "install.sh"
}

The source_commit field is the critical one. When both the installed copy and the source have changed, the agent doing the merge needs a common ancestor — the version they diverged from. Without it, the agent diffs two files blind. With it, the agent can retrieve that version from Git and compare it with both changed copies. If the recorded version is unavailable, keep the two copies and resolve their differences explicitly rather than inventing a base.

The source_type tells the dependency checker which collection a skill belongs to. The March installer checks the dependencies listed in depends_on, looks for each installed dependency and compares its type with the hierarchy. It reports missing dependencies and violations after copying; that warning needs resolution. Within hours of adding depends_on to all 38 skills across the three repos, I found two private skills that referenced public skills by name without declaring the dependency. Writing down those relationships made the omissions visible. Once declared, they could be checked on later installations.

Two installers, different capabilities

The March install.sh was a POSIX shell script using Git, a checksum utility and standard Unix commands. It cloned, copied, wrote provenance and checked declared dependencies. On drift, it warned and overwrote. That made it a bootstrap path for first setup, or for CI environments where no agent was available; reconciling local improvements belonged before replacement.

synthesis-skills-manager is itself a skill: a SKILL.md that teaches an AI agent how to manage the ecosystem. It adds semantic merging to the mechanical installation work. The agent reads the source, installed copy and retained base, identifies each side's improvements, and keeps compatible changes from both. A reordered section can coexist with a new local step. For a true conflict, the manager's instructions say to present both versions for a decision. They also require preserving user-specific Configuration values.

Shell scripts handle mechanical operations well: copying files, computing checksums, writing JSON and checking declared dependencies. Deciding whether two changes to the same methodology conflict or complement each other requires semantic judgment. A text merger can combine separate changes and can flag overlapping edits even when their intent is compatible. An agent that understands the methodology can resolve most drift without human intervention, because methodology changes are usually additive.

Configuration separation

Nine of the 38 skills need user-specific values: file paths, URLs, alert sounds, Slack channels. When those values are scattered through the instructions, every update is a risk. The pattern I landed on is a ## Configuration section near the top with a table:

## Configuration

| Setting | Value | Description |
|---------|-------|-------------|
| `daily_plans_path` | `daily-plans/` | Where daily action plans are saved (relative to the personal ai-knowledge repo) |
| `alert_sound` | `/System/Library/Sounds/Glass.aiff` | Completion alert |

Instructions reference settings by name. The manager’s merge instructions preserve locally configured values during updates; the March shell bootstrap would instead replace the copied file. This is the same separation application developers make between code and environment variables — methodology and configuration ship in the same file but change at different rates and for different reasons.

The practical benefit showed up during the migration itself. Several skills that started as private turned out to be generally useful once the project-specific values were extracted into Configuration. The three-repo structure gave those skills a clear promotion path: extract configuration, move to the public repo, update the dependency graph.

When this is overkill

If you have fewer than ten skills from a single source, you don't need three repos. A single repo with install.sh handles that fine. The architecture earns its complexity when skills come from multiple sources with different access levels, when installed copies evolve through daily use, or when you share skills with a team and need to prevent dependency breakage across different people's installations.

The implementation

The synthesis-skills repository contains the public skills, installer, provenance format and manager instructions. The personal and team collections stay in their own private repositories.

Later operating guidance, checked October 4, 2026: The manager’s instructions place improvements in the source repository, then reinstall or update the deployment and check the installed result against source. Use the repository’s current installation instructions for setup.

The artifact type is new. The management problems are not. Provenance tracking, dependency hierarchies, and the distinction between mechanical and semantic operations appear in every mature tooling ecosystem. What is specific to AI agent skills is the bidirectional evolution pattern — methodology improves at the source and at the point of use simultaneously — and the fact that an AI agent is the right tool to resolve the resulting drift. That loop, where AI-native tooling manages AI-native artifacts, is what makes this architecture work.


This is part of a series on synthesis coding — the practice of building software through human-AI collaboration where the human provides direction, judgment, and domain expertise while the AI provides execution speed and breadth.

Rajiv Pant is President of Flatiron Software and Snapshot AI, where he leads organizational growth and AI innovation. He is former Chief Product & Technology Officer at The Wall Street Journal and Hearst Magazines, and former Chief Technology Officer at The New York Times. Earlier in his career, he headed technology for Condé Nast's brands including Reddit. Rajiv coined the terms "synthesis engineering" and "synthesis coding" to describe the systematic integration of human expertise with AI capabilities in professional software development. Connect with him on LinkedIn or read more at rajiv.com.