Centralizing Hermes Agent SKILL.md via Git Tap Lets Multiple Instances Share the Same Skill Base

When operating AI agents at the team level, you'll eventually hit this situation: a deployment checklist task that your local Hermes handled perfectly last week gets approached from scratch by an instance running on a colleague's machine — as if it's seeing it for the first time. Each agent independently accumulates experience, but that experience never compounds into a team asset. This isn't just an inefficiency problem — as the number of agents grows, the gap in "who knows what" widens exponentially. When I started running around three instances myself, I kept running into "this instance doesn't know that skill" moments and ended up manually copy-pasting files around, which quickly proved to be an unsustainable approach.

Combining Hermes Agent's automatic SKILL.md generation with the Git Tap system can largely solve this problem. The experience an agent builds while performing complex tasks gets automatically extracted into a standardized document format, uploaded to a team Git repository, and other instances can sync with a single command. Git becomes the single source of truth. After reading this article, you'll be able to set up a multi-agent GitOps pattern you can apply to a real team — from Hermes's skill auto-generation mechanism, to team Tap repository configuration, to running multiple instances in parallel.

Core Concepts

When SKILL.md Gets Generated and Its Structure

When Hermes Agent completes a complex task involving five or more consecutive tool calls, it automatically extracts that experience into a SKILL.md file. The storage path follows the pattern ~/.hermes/skills/<category>/<skill-name>/SKILL.md, where the category and skill name are automatically inferred from the task's context.

yaml

# ~/.hermes/skills/deployment/deploy-checklist/SKILL.md
---
name: deploy-checklist
description: 스테이징 → 프로덕션 배포 전 확인 절차 자동화
metadata:
  type: workflow
  tools: [bash, github, slack]
  created: 2026-05-16
  version: 1.2.0
---
 
## 배포 전 확인 절차
 
이 스킬은 배포 전 다음 단계를 순서대로 처리합니다...

What is the SKILL.md format? It's an agent experience-sharing document format designed to be recognized in common by multiple agent platforms including Hermes, Claude Code, and Codex. It stores skill metadata in frontmatter (name, description, metadata) and describes procedures in the body. Supported fields can vary subtly between platforms, so defining a shared team template in advance makes parsing and searching much easier down the line.

As of v0.14.0, a self-evolving mechanism is also built in. If an existing skill is detected as outdated or incomplete during actual use, the agent automatically patches it. This seems quite convenient at first — but honestly, it's a double-edged sword. The agent might modify skills in a way that skews quality metrics, or if configured to commit directly to main without going through a PR, the skill can drift in unknown directions at some point. When enabling the self-evolving setting, it was much safer for skill quality to limit the scope of automatic patches and ensure merges only happen via PRs by setting up branch protection rules.

The Tap System: Git Repositories as a Skill Registry

A Tap is the unit through which Hermes distributes skills. The key point is that no separate registry server is needed. Just set up the prescribed directory structure in a single GitHub repository, and that becomes your team's skill registry.

my-org/hermes-skills
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── deploy-checklist/
│   │   └── SKILL.md
│   └── incident-response/
│       ├── SKILL.md
│       └── references/
│           └── runbook.md
└── README.md

The skills/ directory under the root is the core, and within it you just need to maintain the structure of skill-name folder → SKILL.md. Reference documents (runbooks, config files, etc.) can be placed in a references/ subdirectory alongside the skill, allowing the skill document to reference them via relative paths.

Single Source of Truth By designating a single Git repository as the official source for skills, tracking which version of a skill any given instance is using and rolling back becomes naturally handled through standard Git workflows.

Profile Distribution: Packaging the Entire Team Configuration Beyond Skills

Profile Distribution, added in v0.14.0, is a feature that packages not just skills but the entire set of personality settings, cron jobs, and MCP connection configurations into a single Git repository for distribution. It can reduce the time it takes a new team member to configure their agent environment from hours to minutes. Team members sync to the latest team configuration with a single hermes profile update <name> command.

Practical Application

Basic Setup — Teams Just Getting Started

Example 1: Initial Team Tap Repository Setup

This is the most basic way to get started. You set up the structure in an empty GitHub repository, and team members add it as a Tap.

bash

# 0. First, create an empty private repository on GitHub
#    github.com/new → Repository name: hermes-skills, select Private, then create
 
# 1. Initialize the skill repository locally
mkdir hermes-skills && cd hermes-skills
git init
mkdir -p skills/code-review skills/deploy-checklist
 
# 2. Copy existing local skills to the repository
cp ~/.hermes/skills/deployment/deploy-checklist/SKILL.md \
   skills/deploy-checklist/SKILL.md
 
# 3. Push to GitHub
git add . && git commit -m "init: 팀 스킬 베이스 초기 구성"
git remote add origin https://github.com/my-org/hermes-skills.git
git push -u origin main

Team member onboarding is just this:

bash

# Set up a GitHub Personal Access Token for private repository access
# GitHub → Settings → Developer settings → Personal access tokens (Classic)
# Required permissions: repo (Read access to code and metadata)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# For permanent registration, add the above line to ~/.zshrc or ~/.bashrc
 
# Add the Tap on a team member's machine
hermes skills tap add my-org/hermes-skills
 
# Sync all skills
hermes skills sync
 
# Verify synced skills
hermes skills list

Command	Role
`tap add`	Register a GitHub repository as a skill source
`skills sync`	Sync the latest skills from registered Taps to local
`skills list`	View the list of currently available skills
`skills tap remove`	Unregister a Tap

Example 2: Automatic Skill Capture → Git Contribution with hermes-skill-factory

Manually copying skills every time gets tedious quickly. Attaching the hermes-skill-factory plugin lets it detect patterns during workflow execution, automatically generate a SKILL.md, and even open a PR.

bash

# Install the hermes-skill-factory plugin
hermes plugins install hermes-skill-factory
 
# Set the Tap repository path for the plugin to watch
hermes config set skill-factory.tap-repo my-org/hermes-skills
hermes config set skill-factory.auto-pr true

After this, when an agent completes a complex task involving five or more consecutive tool calls, the plugin automatically handles the following flow:

Task completed
  → SKILL.md auto-generated (~/.hermes/skills/...)
  → feature/skill-<name> branch created in Tap repository
  → SKILL.md committed & pushed
  → PR automatically opened (reviewers can be assigned)

The key point of this pattern is that the agent opens a PR rather than merging directly to main. This naturally maintains the boundary between automation and human review through the Git PR workflow, making it the safest configuration to use in practice.

Advanced Expansion — Next Steps for Teams Already in Operation

Example 3: Parallel Multi-Instance Execution Using Git Worktree

This is a setup where multiple agent instances work on different feature branches in the same repository while sharing only the skill base. Using Git Worktree lets you maintain multiple checkouts, which cleanly isolates instances.

bash

# Clone the main repository
git clone https://github.com/my-org/project.git
cd project
 
# Create separate Worktrees for each agent instance
git worktree add ../agent-feature-a feature/a
git worktree add ../agent-feature-b feature/b
 
# Run instance A (separate terminal)
# hermes start: starts a Hermes agent interactive session using the current directory as context
# You can enter task instructions directly or automate with a script
cd ../agent-feature-a && hermes start
 
# Run instance B (another terminal)
cd ../agent-feature-b && hermes start
 
# Both instances share the same ~/.hermes/skills/ path
# A single Tap sync applies skills to all instances
hermes skills sync  # works regardless of which path you run it from

Git Worktree A feature that lets you check out multiple branches from a single Git repository simultaneously into different directories. It saves disk space compared to cloning the entire repository per instance, while still keeping each working environment isolated.

Example 4: FluxCD-Style Signed Skill Deployment

In Kubernetes/GitOps environments, you can reference FluxCD's agent-skills repository pattern. This approach packages skills as OCI artifacts and signs them with cosign to enforce that agents only use trusted skills.

bash

# Flux Operator CLI pulls skills after verifying signature
flux agent-skills pull \
  --source ghcr.io/fluxcd/agent-skills:latest \
  --verify-signature \
  --output .agents/skills/
 
# Extracted skill structure
# .agents/skills/
# ├── gitops-knowledge/SKILL.md
# ├── gitops-repo-audit/SKILL.md
# └── gitops-cluster-debug/SKILL.md

OCI Artifacts & cosign A method of packaging and distributing files via container image registries (like ghcr.io). cosign is an open-source tool that attaches digital signatures to these artifacts to verify whether they've been tampered with. Since agents will outright refuse to execute unsigned skills, this is suitable for environments that need strict control over provenance and integrity. It has a steep learning curve if you lack DevOps experience, so it's worth getting comfortable with the GitHub-based Tap setup first before exploring this approach.

Pros and Cons Analysis

Advantages

Item	Details
Built-in version control	Skill change history, rollbacks, and audit trails are all handled with a single `git log`
Reduced onboarding time	New team members/instances can sync the entire skill base with just two commands: `tap add` + `skills sync`
CI/CD integration	Skill quality validation, automated deployment, and rollback on failure can be layered on top of existing pipelines
Heterogeneous agent support	SKILL.md is recognized across Claude Code, Codex, and Hermes, enabling cross-platform knowledge sharing
Self-evolving loop	A continuous improvement cycle forms naturally, where agents improve skills during actual use and contribute via PRs

Disadvantages and Caveats

Item	Details	Mitigation
Review fatigue	A flood of agent-generated PRs can rapidly increase the burden on human reviewers	Configuring quality gates in CI — such as SKILL.md format validation, sensitive data scanning, and duplicate detection — lets reviewers focus purely on content, which made things much more manageable
Authentication management	Private Taps require a `GITHUB_TOKEN`, which risks being exposed in skill files	Adding secrets scanning to CI and attaching a pre-commit hook to prevent credentials from being included in SKILL.md is the safe approach. Using it alongside the `detect-secrets` plugin automatically catches this before commits
Skill duplication/conflicts	When multiple instances generate skills independently, similar skills accumulate as duplicates	Using a deduplication tool like SkillClaw, or defining a shared team naming convention (category/skill-name convention) in advance, is far more effective
Format fragmentation	SKILL.md frontmatter fields differ subtly between platforms	Placing a `SKILL_TEMPLATE.md` at the repository root and guiding new skill creation to be based on it makes batch parsing and searching much easier later
Self-evolving contamination	Skills may be automatically modified in a way that skews quality metrics	Explicitly limiting the scope of automatic patches and setting up branch protection rules to prevent direct commits to main without going through a PR was the most reliable way to prevent this

Quality Gate (Guardrail) A step in the CI pipeline that automatically validates a skill PR before it gets merged. This can include SKILL.md format validation, sensitive data scanning, and duplicate skill detection.

The Most Common Mistakes in Practice

Leaving the skill repository public — Skills often contain detailed internal system structures, tool names, and process procedures, making them sensitive information in many cases. It's best to start private and carefully review the scope of visibility.
Allowing self-evolving without limits — It's convenient that an agent can automatically patch skills, but configuring it to commit directly to the main branch without going through a PR can cause skills to drift in unknown directions at some point. Having auto-patches go through PRs was the most reliable way to prevent this.
Starting without a shared team SKILL.md template — If each agent generates frontmatter fields differently, batch parsing and searching becomes difficult later. The time spent creating a SKILL_TEMPLATE.md at the start of the repository and locking in conventions is never wasted.

Closing Thoughts

Once agent instances start multiplying, you'll find yourself repeatedly hitting "this instance doesn't know that skill" moments and spending more time than expected manually copy-pasting files. The biggest change I felt after centralizing SKILL.md with Git was that when adding a new instance, I could focus on the work itself rather than on setup time. This structure — with Git as the single source of truth for skills — demonstrates its value more clearly the more agents you have. Gartner predicts that by end of 2026, 40% of enterprise applications will embed task-specific AI agents (compared to less than 5% as of 2025). Experimenting with this structure at a small scale within your team now versus trying to sort things out after the scale grows comes with quite a different cost.

Three steps you can start with right now:

Create one Tap repository — Create a <org>/hermes-skills private repository on GitHub, initialize a skills/ directory, copy the most frequently used skill from your local ~/.hermes/skills/ to skills/<name>/SKILL.md, and commit it.
Test Tap sharing with one team member — Verify that sync works with hermes skills tap add <org>/hermes-skills && hermes skills sync, then validate with a simple task that the shared skill actually works in your colleague's instance.
Set up the skill PR workflow — Install hermes-skill-factory, turn on the auto-pr: true option, and review the first auto-generated PR from the agent to establish your quality gate standards. The quality of the first PR will immediately give you a sense of what validations you'll need.

Follow this blog's series tag to catch the follow-up content as it comes out.

References

#HermesAgent#GitOps#SKILL.md#멀티에이전트#GitWorktree#FluxCD#OCI아티팩트#AI에이전트#지식공유#CI-CD

Centralizing Hermes Agent SKILL.md via Git Tap Lets Multiple Instances Share the Same Skill Base | DEV BAK - 기술블로그

Centralizing Hermes Agent SKILL.md via Git Tap Lets Multiple Instances Share the Same Skill Base

Core Concepts

When SKILL.md Gets Generated and Its Structure

yaml

# ~/.hermes/skills/deployment/deploy-checklist/SKILL.md
---
name: deploy-checklist
description: 스테이징 → 프로덕션 배포 전 확인 절차 자동화
metadata:
  type: workflow
  tools: [bash, github, slack]
  created: 2026-05-16
  version: 1.2.0
---
 
## 배포 전 확인 절차
 
이 스킬은 배포 전 다음 단계를 순서대로 처리합니다...

What is the SKILL.md format? It's an agent experience-sharing document format designed to be recognized in common by multiple agent platforms including Hermes, Claude Code, and Codex. It stores skill metadata in frontmatter (name, description, metadata) and describes procedures in the body. Supported fields can vary subtly between platforms, so defining a shared team template in advance makes parsing and searching much easier down the line.

The Tap System: Git Repositories as a Skill Registry

my-org/hermes-skills
├── skills/
│   ├── code-review/
│   │   └── SKILL.md
│   ├── deploy-checklist/
│   │   └── SKILL.md
│   └── incident-response/
│       ├── SKILL.md
│       └── references/
│           └── runbook.md
└── README.md

Single Source of Truth By designating a single Git repository as the official source for skills, tracking which version of a skill any given instance is using and rolling back becomes naturally handled through standard Git workflows.

Profile Distribution: Packaging the Entire Team Configuration Beyond Skills

Practical Application

Basic Setup — Teams Just Getting Started

Example 1: Initial Team Tap Repository Setup

This is the most basic way to get started. You set up the structure in an empty GitHub repository, and team members add it as a Tap.

bash

# 0. First, create an empty private repository on GitHub
#    github.com/new → Repository name: hermes-skills, select Private, then create
 
# 1. Initialize the skill repository locally
mkdir hermes-skills && cd hermes-skills
git init
mkdir -p skills/code-review skills/deploy-checklist
 
# 2. Copy existing local skills to the repository
cp ~/.hermes/skills/deployment/deploy-checklist/SKILL.md \
   skills/deploy-checklist/SKILL.md
 
# 3. Push to GitHub
git add . && git commit -m "init: 팀 스킬 베이스 초기 구성"
git remote add origin https://github.com/my-org/hermes-skills.git
git push -u origin main

Team member onboarding is just this:

bash

# Set up a GitHub Personal Access Token for private repository access
# GitHub → Settings → Developer settings → Personal access tokens (Classic)
# Required permissions: repo (Read access to code and metadata)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# For permanent registration, add the above line to ~/.zshrc or ~/.bashrc
 
# Add the Tap on a team member's machine
hermes skills tap add my-org/hermes-skills
 
# Sync all skills
hermes skills sync
 
# Verify synced skills
hermes skills list

Command	Role
`tap add`	Register a GitHub repository as a skill source
`skills sync`	Sync the latest skills from registered Taps to local
`skills list`	View the list of currently available skills
`skills tap remove`	Unregister a Tap

Example 2: Automatic Skill Capture → Git Contribution with hermes-skill-factory

bash

# Install the hermes-skill-factory plugin
hermes plugins install hermes-skill-factory
 
# Set the Tap repository path for the plugin to watch
hermes config set skill-factory.tap-repo my-org/hermes-skills
hermes config set skill-factory.auto-pr true

After this, when an agent completes a complex task involving five or more consecutive tool calls, the plugin automatically handles the following flow:

Task completed
  → SKILL.md auto-generated (~/.hermes/skills/...)
  → feature/skill-<name> branch created in Tap repository
  → SKILL.md committed & pushed
  → PR automatically opened (reviewers can be assigned)

Advanced Expansion — Next Steps for Teams Already in Operation

Example 3: Parallel Multi-Instance Execution Using Git Worktree

bash

# Clone the main repository
git clone https://github.com/my-org/project.git
cd project
 
# Create separate Worktrees for each agent instance
git worktree add ../agent-feature-a feature/a
git worktree add ../agent-feature-b feature/b
 
# Run instance A (separate terminal)
# hermes start: starts a Hermes agent interactive session using the current directory as context
# You can enter task instructions directly or automate with a script
cd ../agent-feature-a && hermes start
 
# Run instance B (another terminal)
cd ../agent-feature-b && hermes start
 
# Both instances share the same ~/.hermes/skills/ path
# A single Tap sync applies skills to all instances
hermes skills sync  # works regardless of which path you run it from

Git Worktree A feature that lets you check out multiple branches from a single Git repository simultaneously into different directories. It saves disk space compared to cloning the entire repository per instance, while still keeping each working environment isolated.

Example 4: FluxCD-Style Signed Skill Deployment

bash

# Flux Operator CLI pulls skills after verifying signature
flux agent-skills pull \
  --source ghcr.io/fluxcd/agent-skills:latest \
  --verify-signature \
  --output .agents/skills/
 
# Extracted skill structure
# .agents/skills/
# ├── gitops-knowledge/SKILL.md
# ├── gitops-repo-audit/SKILL.md
# └── gitops-cluster-debug/SKILL.md

OCI Artifacts & cosign A method of packaging and distributing files via container image registries (like ghcr.io). cosign is an open-source tool that attaches digital signatures to these artifacts to verify whether they've been tampered with. Since agents will outright refuse to execute unsigned skills, this is suitable for environments that need strict control over provenance and integrity. It has a steep learning curve if you lack DevOps experience, so it's worth getting comfortable with the GitHub-based Tap setup first before exploring this approach.

Pros and Cons Analysis

Advantages

Item	Details
Built-in version control	Skill change history, rollbacks, and audit trails are all handled with a single `git log`
Reduced onboarding time	New team members/instances can sync the entire skill base with just two commands: `tap add` + `skills sync`
CI/CD integration	Skill quality validation, automated deployment, and rollback on failure can be layered on top of existing pipelines
Heterogeneous agent support	SKILL.md is recognized across Claude Code, Codex, and Hermes, enabling cross-platform knowledge sharing
Self-evolving loop	A continuous improvement cycle forms naturally, where agents improve skills during actual use and contribute via PRs

Disadvantages and Caveats

Item	Details	Mitigation
Review fatigue	A flood of agent-generated PRs can rapidly increase the burden on human reviewers	Configuring quality gates in CI — such as SKILL.md format validation, sensitive data scanning, and duplicate detection — lets reviewers focus purely on content, which made things much more manageable
Authentication management	Private Taps require a `GITHUB_TOKEN`, which risks being exposed in skill files	Adding secrets scanning to CI and attaching a pre-commit hook to prevent credentials from being included in SKILL.md is the safe approach. Using it alongside the `detect-secrets` plugin automatically catches this before commits
Skill duplication/conflicts	When multiple instances generate skills independently, similar skills accumulate as duplicates	Using a deduplication tool like SkillClaw, or defining a shared team naming convention (category/skill-name convention) in advance, is far more effective
Format fragmentation	SKILL.md frontmatter fields differ subtly between platforms	Placing a `SKILL_TEMPLATE.md` at the repository root and guiding new skill creation to be based on it makes batch parsing and searching much easier later
Self-evolving contamination	Skills may be automatically modified in a way that skews quality metrics	Explicitly limiting the scope of automatic patches and setting up branch protection rules to prevent direct commits to main without going through a PR was the most reliable way to prevent this

Quality Gate (Guardrail) A step in the CI pipeline that automatically validates a skill PR before it gets merged. This can include SKILL.md format validation, sensitive data scanning, and duplicate skill detection.

The Most Common Mistakes in Practice

Leaving the skill repository public — Skills often contain detailed internal system structures, tool names, and process procedures, making them sensitive information in many cases. It's best to start private and carefully review the scope of visibility.
Allowing self-evolving without limits — It's convenient that an agent can automatically patch skills, but configuring it to commit directly to the main branch without going through a PR can cause skills to drift in unknown directions at some point. Having auto-patches go through PRs was the most reliable way to prevent this.
Starting without a shared team SKILL.md template — If each agent generates frontmatter fields differently, batch parsing and searching becomes difficult later. The time spent creating a SKILL_TEMPLATE.md at the start of the repository and locking in conventions is never wasted.

Closing Thoughts

Three steps you can start with right now:

Create one Tap repository — Create a <org>/hermes-skills private repository on GitHub, initialize a skills/ directory, copy the most frequently used skill from your local ~/.hermes/skills/ to skills/<name>/SKILL.md, and commit it.
Test Tap sharing with one team member — Verify that sync works with hermes skills tap add <org>/hermes-skills && hermes skills sync, then validate with a simple task that the shared skill actually works in your colleague's instance.
Set up the skill PR workflow — Install hermes-skill-factory, turn on the auto-pr: true option, and review the first auto-generated PR from the agent to establish your quality gate standards. The quality of the first PR will immediately give you a sense of what validations you'll need.

Follow this blog's series tag to catch the follow-up content as it comes out.

References

#HermesAgent#GitOps#SKILL.md#멀티에이전트#GitWorktree#FluxCD#OCI아티팩트#AI에이전트#지식공유#CI-CD

Core Concepts

When SKILL.md Gets Generated and Its Structure

The Tap System: Git Repositories as a Skill Registry

Profile Distribution: Packaging the Entire Team Configuration Beyond Skills

Practical Application

Basic Setup — Teams Just Getting Started

Example 1: Initial Team Tap Repository Setup

Example 2: Automatic Skill Capture → Git Contribution with hermes-skill-factory

Advanced Expansion — Next Steps for Teams Already in Operation

Example 3: Parallel Multi-Instance Execution Using Git Worktree

Example 4: FluxCD-Style Signed Skill Deployment

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

The Most Common Mistakes in Practice

Closing Thoughts

References

Core Concepts

When SKILL.md Gets Generated and Its Structure

The Tap System: Git Repositories as a Skill Registry

Profile Distribution: Packaging the Entire Team Configuration Beyond Skills

Practical Application

Basic Setup — Teams Just Getting Started

Example 1: Initial Team Tap Repository Setup

Example 2: Automatic Skill Capture → Git Contribution with hermes-skill-factory

Advanced Expansion — Next Steps for Teams Already in Operation

Example 3: Parallel Multi-Instance Execution Using Git Worktree

Example 4: FluxCD-Style Signed Skill Deployment

Pros and Cons Analysis

Advantages

Disadvantages and Caveats

The Most Common Mistakes in Practice

Closing Thoughts

References

Recommended Posts

Building a Local LLM Infrastructure with Ollama + Hermes — $0 API Costs, Zero Data Leakage

OpenCode vs Claude Code: Comparing Terminal AI Agents and Choosing the Right One for Your Team

Building a TypeScript LSP Self-Correction Loop with OpenCode — AI That Catches Its Own Type Errors

Automating Deployment Pipelines with Hermes Agent

AI Agent-Based CI/CD Automation — Hermes Agent Crons' state.db Structure and Isolated Execution Mechanics

Hermes Agent SOUL.md and the 5-Pillar Architecture — An Inside Look at the Tier 3 Skill Auto-Generation Mechanism