npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@superkut/subagents

v0.6.0

Published

CLI for installing cross-agent subagent definitions from git repos, URLs, or local paths

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

superkutsuperkut

Keywords

cliagent-subagentssubagentssubagentsai-agentsampclaude-codecodexcursorfactoryopencode

Readme

subagents

A CLI for installing cross-agent subagent definitions from git repos, URLs, or local paths into target agent directories.

Supports OpenCode, Claude Code, Codex, Cursor, and 2 more.

Install a Subagent

npx @superkut/subagents add VoltAgent/awesome-claude-code-subagents

Source Formats

# GitHub shorthand (owner/repo)
npx @superkut/subagents add VoltAgent/awesome-claude-code-subagents

# Full GitHub URL
npx @superkut/subagents add https://github.com/VoltAgent/awesome-claude-code-subagents

# Direct path to a subagent in a repo
npx @superkut/subagents add https://github.com/owner/repo/tree/main/agents/my-subagent

# GitLab URL
npx @superkut/subagents add https://gitlab.com/org/repo

# Any git URL
npx @superkut/subagents add [email protected]:owner/repo.git

# Local path
npx @superkut/subagents add ./my-local-subagents

# Install a specific subagent by name
npx @superkut/subagents add owner/repo@subagent-name

Options

| Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | -g, --global | Install to user directory instead of project | | -a, --agent <agents...> | Target specific agents (e.g., claude-code, codex). See Supported Agents | | -s, --skill <names...> | Install specific subagents by name (use '*' for all) | | -l, --list | List available subagents without installing | | --copy | Copy files instead of symlinking to agent directories | | -y, --yes | Skip all confirmation prompts | | --all | Install all subagents to all agents without prompts |

Examples

# List subagents in a repository
npx subagents add VoltAgent/awesome-claude-code-subagents --list

# Install specific subagents
npx subagents add owner/repo --skill code-reviewer --skill test-runner

# Install to specific agents
npx subagents add owner/repo -a claude-code -a opencode

# Non-interactive installation (CI/CD friendly)
npx subagents add owner/repo --skill code-reviewer -g -a claude-code -y

# Install all subagents from a repo to all agents
npx subagents add owner/repo --all

# Install all subagents to specific agents
npx subagents add owner/repo --skill '*' -a claude-code

# Install specific subagents to all agents
npx subagents add owner/repo --agent '*' --skill code-reviewer

Installation Scope

| Scope | Flag | Location | Use Case | | ----------- | --------- | ------------------- | --------------------------------------------- | | Project | (default) | ./<agent>/agents/ | Committed with your project, shared with team | | Global | -g | ~/<agent>/agents/ | Available across all projects |

Installation Methods

When installing interactively, you can choose:

| Method | Description | | ------------------------- | ------------------------------------------------------------------------------------------- | | Symlink (Recommended) | Creates symlinks from each agent to a canonical copy. Single source of truth, easy updates. | | Copy | Creates independent copies for each agent. Use when symlinks aren't supported. |

Other Commands

| Command | Description | | ---------------------------------------- | ------------------------------------------------ | | npx @superkut/subagents list | List installed subagents (alias: ls) | | npx @superkut/subagents find [query] | Search for subagents interactively or by keyword | | npx @superkut/subagents remove [name] | Remove installed subagents from agents | | npx @superkut/subagents update [names] | Update installed subagents to latest versions | | npx @superkut/subagents init [name] | Create a new AGENT.md template |

subagents list

List all installed subagents. Similar to npm ls.

# List all installed subagents (project and global)
npx subagents list

# List only global subagents
npx subagents ls -g

# Filter by specific agents
npx subagents ls -a claude-code -a cursor

subagents find

Search for subagents interactively or by keyword.

# Interactive search (fzf-style)
npx subagents find

# Search by keyword
npx subagents find typescript

subagents update

# Update all subagents (interactive scope prompt)
npx subagents update

# Update a single subagent by name
npx subagents update my-subagent

# Update multiple specific subagents
npx subagents update code-reviewer test-runner

# Update only global or project subagents
npx subagents update -g
npx subagents update -p

# Non-interactive (auto-detects scope: project if in a project, else global)
npx subagents update -y

| Option | Description | | --------------- | ------------------------------------------------------------------------- | | -g, --global | Only update global subagents | | -p, --project | Only update project subagents | | -y, --yes | Skip scope prompt (auto-detect: project if in a project dir, else global) | | [names...] | Update specific subagents by name instead of all |

subagents init

# Create AGENT.md in current directory
npx subagents init

# Create a new subagent in a subdirectory
npx subagents init my-subagent

subagents remove

Remove installed subagents from agents.

# Remove interactively (select from installed subagents)
npx subagents remove

# Remove specific subagent by name
npx subagents remove my-subagent

# Remove multiple subagents
npx subagents remove code-reviewer test-runner

# Remove from global scope
npx subagents remove --global my-subagent

# Remove from specific agents only
npx subagents remove --agent claude-code cursor my-subagent

# Remove all installed subagents without confirmation
npx subagents remove --all

# Remove all subagents from a specific agent
npx subagents remove --skill '*' -a cursor

# Remove a specific subagent from all agents
npx subagents remove my-subagent --agent '*'

# Use 'rm' alias
npx subagents rm my-subagent

| Option | Description | | -------------- | ------------------------------------------------ | | -g, --global | Remove from global scope (~/) instead of project | | -a, --agent | Remove from specific agents (use '*' for all) | | -s, --skill | Specify subagents to remove (use '*' for all) | | -y, --yes | Skip confirmation prompts | | --all | Shorthand for --skill '*' --agent '*' -y |

What are Subagents?

Subagents are named, isolated agent personas defined in single Markdown files with YAML frontmatter. Each file contains a name and description (required), plus optional fields like tools, model, and mode. The body of the file is the agent's system prompt.

---
name: code-reviewer
description: Reviews diffs for correctness and risks
tools: [Read, Grep, Glob, Bash]
model: inherit
---

You are a focused code reviewer. …

Subagents are installed verbatim to each target agent's directory — no per-target frontmatter translation in v1.

Subagent Discovery

The CLI discovers subagents by scanning for *.md files with name + description YAML frontmatter. It searches these locations within a repository:

  • Root directory (any .md file with valid frontmatter)
  • agents/
  • subagents/
  • droids/
  • .agents/agents/
  • .claude/agents/
  • .codex/agents/
  • .cursor/agents/
  • .factory/droids/
  • .opencode/agents/

If no subagents are found in standard locations, a recursive search is performed.

Supported Agents

Subagents can be installed to any of these agents:

| Agent | --agent | Project Path | Global Path | | --------------- | ------------- | ------------------- | ---------------------------- | | Amp | amp | .agents/agents/ | ~/.config/agents/agents/ | | Claude Code | claude-code | .claude/agents/ | ~/.claude/agents/ | | Codex | codex | .codex/agents/ | ~/.codex/agents/ | | Cursor | cursor | .cursor/agents/ | ~/.cursor/agents/ | | Factory (Droid) | factory | .factory/droids/ | ~/.factory/droids/ | | OpenCode | opencode | .opencode/agents/ | ~/.config/opencode/agents/ |

The CLI automatically detects which coding agents you have installed. If none are detected, you'll be prompted to select which agents to install to.

Creating Subagents

Subagents are Markdown files with YAML frontmatter:

---
name: my-subagent
description: What this subagent does and when to use it
---

# My Subagent

Instructions for the agent to follow when this subagent is activated.

## When to Use

Describe the scenarios where this subagent should be used.

## Steps

1. First, do this
2. Then, do that

Required Fields

  • name: Unique identifier (lowercase, hyphens allowed)
  • description: Brief explanation of what the subagent does

Optional Fields

  • tools: Array of tool names the subagent can use (e.g., [Read, Grep, Glob, Bash])
  • model: Model specification (e.g., inherit to use the parent agent's model)
  • mode: Agent mode (e.g., subagent)
  • metadata.internal: Set to true to hide the subagent from normal discovery. Internal subagents are only visible and installable when INSTALL_INTERNAL_SKILLS=1 is set.
---
name: my-internal-subagent
description: An internal subagent not shown by default
metadata:
  internal: true
---

Troubleshooting

"No subagents found"

Ensure the repository contains valid .md files with both name and description in the YAML frontmatter.

Subagent not loading in agent

  • Verify the subagent was installed to the correct path
  • Check the agent's documentation for subagent/agent loading requirements
  • Ensure the YAML frontmatter is valid

Permission errors

Ensure you have write access to the target directory.

Environment Variables

| Variable | Description | | ------------------------- | ----------------------------------------------------------------------------- | | INSTALL_INTERNAL_SKILLS | Set to 1 or true to show and install subagents marked as internal: true | | DISABLE_TELEMETRY | Set to disable anonymous usage telemetry | | DO_NOT_TRACK | Alternative way to disable telemetry | | GITHUB_TOKEN | GitHub API token for higher rate limits | | GH_TOKEN | Alternative GitHub API token |

# Install internal subagents
INSTALL_INTERNAL_SKILLS=1 npx @superkut/subagents add owner/repo --list

# Use a GitHub token for higher rate limits
GITHUB_TOKEN=ghp_xxx npx @superkut/subagents add owner/repo

Telemetry

This CLI collects anonymous usage data to help improve the tool. No personal information is collected.

Telemetry is automatically disabled in CI environments.

Related Links

License

MIT