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

> Learn the complete workflow to create and install custom Claude code agents from GitHub. Author, publish, and install agents easily using CLI or swarmvault.

- Repository: [Daniel Avila/claude-code-templates](https://github.com/davila7/claude-code-templates)
- Tags: how-to-guide
- Published: 2026-04-26

---

**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.

```markdown
---
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`](https://github.com/davila7/claude-code-templates/blob/main/.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`](https://github.com/davila7/claude-code-templates/blob/main/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:

```bash
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`](https://github.com/davila7/claude-code-templates/blob/main/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:

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

```

As implemented in [`cli-tool/src/index.js`](https://github.com/davila7/claude-code-templates/blob/main/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:

```bash
swarmvault install --agent my-awesome-agent

```

This command, documented in [`cli-tool/components/skills/development/swarmvault/README.md`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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:

```bash

# 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`](https://github.com/davila7/claude-code-templates/blob/main/cli-tool/components/agents/expert-advisors/agent-installer.md).
- **Reference implementation** details appear in [`cli-tool/src/index.js`](https://github.com/davila7/claude-code-templates/blob/main/cli-tool/src/index.js) (CLI parsing), [`SUBAGENTS_GUIDE.md`](https://github.com/davila7/claude-code-templates/blob/main/SUBAGENTS_GUIDE.md) (directory priorities), and [`agent-expert.md`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/.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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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`](https://github.com/davila7/claude-code-templates/blob/main/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.