Replicating Agentic Workflows: Portable Plugin & Skill Distribution across Machines

Table of Contents

1. The Context / The Problem
2. The Deep-Dive / Root Cause Analysis
3. The Implementation / Architecture
4. Lessons Learned & Best Practices
5. References

The Context / The Problem

Customizing AI coding assistants with specialized agent skills, Model Context Protocol (MCP) servers, and automated workflows transforms developer productivity. However, as engineers move between developer laptops, desktop workstations, and remote cloud devboxes, these carefully tuned agent configurations frequently remain trapped on individual machines.

In our engineering team, developers spent hours crafting custom tool integrations (skills for BGP route inspection, Knot DNS serial recovery, and Incus container lifecycle hooks). Yet whenever a developer provisioned a new machine or spun up an ephemeral cloud workstation, they had to manually recreate config paths, re-authenticate API credentials, and re-link local agent definitions.

We needed a portable, git-backed synchronization system capable of distributing skills, MCP server configurations, and persona instructions seamlessly across macOS, Linux, and FreeBSD environments without leaking private tokens or hardcoding machine-specific file paths.

The Deep-Dive / Root Cause Analysis

Examining why AI agent setups are difficult to synchronize across machines exposed three structural hurdles:

1. Absolute Path Hardcoding

Agent tool definitions often hardcode paths to local virtual environments or binary locations (e.g. /home/user/.local/bin/python3). When synchronized to a machine with a different username or OS layout (like macOS /Users/zoa), tool executions fail with missing executable errors.

2. Secret Infiltration into Git Repositories

MCP configuration files frequently require secret API tokens and database credentials. Naively committing claude.json or config.json to a personal dotfiles repository risks catastrophic secret exposure.

The Implementation / Architecture

We built a declarative agent management system that couples a version-controlled skills repository with environment-variable expansion and dynamic symlink bootstrapping.

1. The Portable Agent Configuration Schema

Configurations use environment-variable interpolation (${HOME}, ${CARGO_HOME}) and decouple secrets into local keyring stores:

{
  "mcpServers": {
    "git-intel": {
      "command": "node",
      "args": ["${HOME}/.agents/mcp/git-intel/index.js"],
      "env": {
        "FORGEJO_API_URL": "https://git.femboy.fan/api/v1",
        "FORGEJO_TOKEN": "${SECRET_FORGEJO_TOKEN}"
      }
    },
    "network-prober": {
      "command": "${HOME}/.local/bin/net-mcp",
      "args": ["--as", "214806"]
    }
  }
}

2. Automated Sync & Bootstrap Script

A lightweight POSIX shell script (sync-agent-skills.sh) clones or pulls the team's skills repository, expands paths, and symlinks skills into the platform-specific config directory:

#!/usr/bin/env bash
set -euo pipefail

SKILLS_REPO="https://git.femboy.fan/infra/agent-skills.git"
TARGET_DIR="${HOME}/.config/antigravity/skills"

echo "=== Bootstrapping Agent Skills & Workflows ==="

mkdir -p "$(dirname "$TARGET_DIR")"
if [ ! -d "$TARGET_DIR/.git" ]; then
    echo "Cloning agent skills repository..."
    git clone "$SKILLS_REPO" "$TARGET_DIR"
else
    echo "Updating existing skills..."
    git -C "$TARGET_DIR" pull --ff-only
fi

# Link individual skills into global assistant path
mkdir -p "${HOME}/.gemini/skills"
for skill in "$TARGET_DIR"/*/; do
    skill_name=$(basename "$skill")
    target_link="${HOME}/.gemini/skills/${skill_name}"
    ln -sfn "$skill" "$target_link"
    echo "Linked skill: ${skill_name} -> ${target_link}"
done

echo "All agent skills synchronized successfully."

Lessons Learned & Best Practices

1. Treat Skills as Versioned Code Artifacts: Maintaining skills in a dedicated Git repository with semantic tags enables team-wide peer review, regression testing, and instant distribution.
2. Never Hardcode Home Directories in MCP Configs: Always resolve paths relative to ${HOME} or through wrapper runner scripts that compute $0 directory offsets.
3. Isolate Secrets via Environment Variables: Feeding sensitive tokens through standard shell environment variables keeps agent manifests safe to share across public or semi-private team repositories.

References

• Model Context Protocol (MCP) Specification
• Dotfiles Management & Symlink Best Practices
• Anthropic Claude Desktop Configuration Reference