Agent loader

Skill samzong/agent-brains/skills/agent-loader

Personal agent brain catalog for coding agents: AGENTS.md, SOUL.md, MEMORY.md, skills, workflows, and a bundled loader.

Install

npx -y skills add samzong/agent-brains --skill agent-loader

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Load or list repo-scoped and user-scoped agent brains. Use when the user asks to load an agent by name, list available agents, inspect agent descriptions or workflows, or start a session or task with a personal agent brain.

SKILL.md

3.8 KB, as published. Nobody here has run it

Agent Loader

Use this skill to list and load agent brains from two scopes:

REPO: $CWD/.agents/agents up to $REPO_ROOT/.agents/agents
USER: $HOME/.agents/agents

Repo scope is searched from the current working directory upward to the repository root. User scope is searched after repo scope. If the same agent name exists in multiple places, the first discovered agent wins.

For a global setup, clone this repository to ~/.agents/agent-brains, then symlink ~/.agents/agents to ~/.agents/agent-brains/agents.

The discovery roots can be overridden with AGENT_BRAINS_ROOT or the script's --root option. Overrides use custom scope.

Modes

List Agents

Use when the user asks what agents exist, asks for agent names, or is unsure which agent to load.

Run the bundled script:

uv run python skills/agent-loader/scripts/list_agents.py

Report each agent's name, description, scope, and path. Discovery only reads AGENTS.md frontmatter; it does not read the body or any other core file. If an agent has no description, say so directly.

List Workflows

Use when the user asks what workflows an agent has, or when loading an agent and a lightweight workflow summary is useful.

Run:

uv run python skills/agent-loader/scripts/list_agents.py --agent <name> --workflows

The script resolves <name> through the same repo/user discovery order, then reads only each workflow's WORKFLOW.md frontmatter. Report each workflow's name, description, and path. Do not read workflow bodies just to list workflows.

Load An Agent

Use when the user names an agent or asks to start working as an agent.

First resolve the agent path:

uv run python skills/agent-loader/scripts/list_agents.py --agent <name>

The script prints:

name<TAB>description<TAB>scope<TAB>path

For the resolved path, read in this order:

path/AGENTS.md
path/SOUL.md
path/MEMORY.md

Then acknowledge the active agent and summarize:

identity
main responsibilities
key operating rules
available skills
available workflows

Do not read every file under memories/ by default. Read a memory file only when AGENTS.md, MEMORY.md, or the user's task points to it.

Do not read every skills/*/SKILL.md by default. Read a skill only when the task matches that skill or the agent's AGENTS.md tells you to use it for the current task.

Do not read every workflows/*/WORKFLOW.md by default. Use the workflow frontmatter list first; read a workflow body only when the current task matches it or the user asks for it.

Validation

If the agent cannot be resolved, list available agents instead of guessing.

If AGENTS.md, SOUL.md, or MEMORY.md is missing, report the missing file and load only the existing files.

If AGENTS.md lacks frontmatter with name and description, report that the agent brain needs metadata cleanup.

If skills/ contains files directly under it instead of skills/SKILL_NAME/SKILL.md, report that the agent brain violates the current skill layout.

If workflows/ contains files directly under it instead of workflows/WORKFLOW_NAME/WORKFLOW.md, report that the agent brain violates the current workflow layout.

If a WORKFLOW.md lacks frontmatter with name and description, report that the workflow needs metadata cleanup.

Boundaries

This skill loads agent context. It does not create, update, or audit agent brains unless the user explicitly asks for that work.

For creating, updating, or auditing agent brains, load agent-creator.