How to Create and Install Custom Claude Code Agents from GitHub: A Complete Workflow

The workflow for creating and installing custom agents from GitHub involves authoring a Markdown file with YAML front-matter, publishing it to a repository (typically VoltAgent/awesome-claude-code-subagents), and installing it via the CLI --agent flag or the swarmvault skill, which downloads the file to your local .claude/agents/ directory.

Custom Claude Code agents are self-contained AI assistants defined as Markdown files with YAML front-matter headers. You can author these agents locally using the davila7/claude-code-templates repository structure, share them via GitHub, and install them into either project-level (./.claude/agents/) or user-level (~/.claude/agents/) directories. This workflow allows teams to distribute specialized coding assistants across projects.

Authoring a Custom Agent File

Claude Code agents require a specific Markdown format that combines metadata with a system prompt.

Required YAML Front-Matter Structure

Every agent file must begin with YAML front-matter declaring the name, description, and optional tools. The body contains the system prompt that guides the AI's behavior.

---
name: my-awesome-agent
description: |
  An agent that helps refactor JavaScript code to use modern ES2024 syntax.
tools: Bash, WebFetch
---
You are a refactoring assistant. When the user provides a code snippet, rewrite it
using the latest language features, preserving functionality and adding helpful
comments.

According to the source in .claude/agents/agent-expert.md, the YAML front-matter is mandatory and the body serves as the system prompt that defines the agent's capabilities.

Directory Placement: Project vs. User Scope

You must place agent files in one of two locations based on scope:

• Project-level: ./.claude/agents/ (highest priority, version-controlled with your repo)
• User-level: ~/.claude/agents/ (available across all projects)

As documented in cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md, the CLI checks the project directory first, falling back to the user directory if the agent is not found locally.

Create a local agent using:

mkdir -p .claude/agents
cat > .claude/agents/my-awesome-agent.md <<'EOF'
---
name: my-awesome-agent
description: Helper for modern JavaScript refactoring.
tools: Bash
---
You are a refactoring assistant...
EOF

Publishing Agents to GitHub

Once authored, publish the agent to make it available for installation:

1. Push to a repository – either your own collection or contribute to the official VoltAgent/awesome-claude-code-subagents repository.
2. Follow the folder convention – place agents under categories/<category-name>/ (e.g., categories/javascript/my-awesome-agent.md).
3. Commit and push – git add . && git commit -m "Add my-awesome-agent" && git push.

The official collection uses raw GitHub URLs for distribution, which the installer accesses at https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/categories/<category>/<agent>.md.

Installing Agents from GitHub

There are two primary methods for retrieving remote agents from GitHub and installing them locally.

Using the CLI --agent Flag

The standard installation method uses the npx command with the --agent flag:

npx claude-code-templates@latest --agent my-awesome-agent --yes

As implemented in cli-tool/src/index.js around line 2870, the CLI parses this flag and delegates to the agent-installer sub-agent if the file is not found locally. The installer prompts for the target location (global or local) and downloads the Markdown file from the raw GitHub URL.

Using the swarmvault Skill

The swarmvault skill provides a convenience wrapper around the same installation logic:

swarmvault install --agent my-awesome-agent

This command, documented in cli-tool/components/skills/development/swarmvault/README.md, executes the same download workflow as the CLI flag but with a simplified interface.

Browsing and Searching Remote Agents

The agent-installer sub-agent (defined in cli-tool/components/agents/expert-advisors/agent-installer.md) supports discovery workflows:

• List categories: Display all available agent categories in the official repository.
• Search agents: Query the central README.md for keywords like "typescript" or "refactoring".
• Browse by category: List all agents within a specific category before selecting one for installation.

Example End-to-End Workflow

This complete example demonstrates creating a TypeScript refactoring agent and installing it via the official collection:

# Step 1: Create the agent locally (optional if installing from GitHub)

mkdir -p .claude/agents
cat > .claude/agents/ts-refactor.md <<'EOF'
---
name: ts-refactor
description: Refactor TypeScript to use strict null checks and modern syntax.
tools: Bash
---
You are a TypeScript refactoring assistant specializing in strict mode conversions.
EOF

# Step 2: Push to GitHub (omitted)

# Step 3: Install from the official collection

npx claude-code-templates@latest --agent ts-refactor --yes

# Output: ✓ Installed ts-refactor.md to ./.claude/agents/

The installer downloads from the raw URL, writes the file to your chosen .claude/agents/ directory, and confirms successful installation.

Summary

• Author agents as Markdown files with YAML front-matter (name, description, optional tools) placed in .claude/agents/ or ~/.claude/agents/.
• Publish agents by pushing to GitHub, preferably under categories/<name>/ in the VoltAgent/awesome-claude-code-subagents repository.
• Install agents using npx claude-code-templates@latest --agent <name> or swarmvault install --agent <name>, which delegates to the agent-installer sub-agent defined in cli-tool/components/agents/expert-advisors/agent-installer.md.
• Reference implementation details appear in cli-tool/src/index.js (CLI parsing), SUBAGENTS_GUIDE.md (directory priorities), and agent-expert.md (file format template).

Frequently Asked Questions

What file format do Claude Code agents use?

Agents use Markdown files with YAML front-matter headers. The front-matter must declare at least name and description, with an optional tools list specifying which Claude Code tools the agent may invoke. The body contains the system prompt that defines the agent's behavior, as shown in the template at .claude/agents/agent-expert.md.

Where should I store custom agents locally?

Store agents in either ./.claude/agents/ for project-specific agents (highest priority) or ~/.claude/agents/ for global access across all projects. According to cli-tool/docs_to_claude/SUBAGENTS_GUIDE.md, Claude Code resolves agents by checking the project directory first, then falling back to the user directory.

How does the agent-installer sub-agent download files from GitHub?

The agent-installer retrieves raw Markdown content from https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/categories/<category>/<agent>.md. It parses the agent name provided via CLI, constructs the raw URL, downloads the file content, and writes it to your selected directory (either ./.claude/agents/ or ~/.claude/agents/). This process is codified in cli-tool/components/agents/expert-advisors/agent-installer.md.

Can I use the swarmvault CLI instead of the standard npx command?

Yes. The swarmvault skill provides an alternative interface via swarmvault install --agent <name>. As documented in cli-tool/components/skills/development/swarmvault/README.md, this command wraps the same installation logic used by the --agent CLI flag, offering identical functionality with a simplified command structure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}