Non-negotiable rules:
- Verify
agentshqavailability before relying on it. - Be explicit about scope: project vs global, specific IDEs vs auto-detect.
- Do not install or remove agents the user did not ask for.
- Confirm ambiguous install targets before making changes.
- Report exactly what was added, removed, or updated.
Find Agents
Inputs
$request: Search terms, repo source, or management intent such aslist,remove, orupdate
Goal
Use agentshq to help the user:
- discover relevant agents
- install agents into one or more CLIs or IDEs
- list current inventory
- remove or update installed agents
- scaffold a new agent when asked
Step 0: Verify runtime prerequisites
Check:
- Node.js availability
npx agentshq --version
If the CLI is unavailable, explain the blocker and stop.
Success criteria: agentshq can be invoked from the current environment.
Step 1: Resolve the user's intent
Determine whether the user wants to:
- search
- install
- list
- remove
- update
- scaffold
Also resolve:
- project vs global scope
- target IDEs/CLIs if specified
- source repo, URL, or local path if installing
If those details are ambiguous, ask before mutating anything.
Success criteria: The exact agentshq action is clear before execution.
Step 2: Run the narrowest relevant command
Command Reference
| Action | Command | Key Flags |
|---|---|---|
| Search | npx agentshq find [query] | interactive picker when no query given |
| Install from repo | npx agentshq add <owner>/<repo> | @<agent-name> for specific agent |
| Install from URL | npx agentshq add <url> | also works with local paths |
| Install scope | -g for global, --ide <name>... for specific IDEs | |
| Install options | --all for all agents to all IDEs, --list to preview | |
| List installed | npx agentshq list | -g for global, --ide <name>, --json |
| Remove | npx agentshq remove [name] | -g for global, --all for all agents |
| Check updates | npx agentshq check | |
| Apply updates | npx agentshq update | |
| Scaffold new | npx agentshq init [name] |
When installing, respect:
- explicit
--ide...choices when the user gave them -gonly when the user asked for global scope--listwhen the user wants to inspect a source before installing
Supported IDEs
The CLI supports 43+ IDEs. Common ones:
| IDE | Format |
|---|---|
| Claude Code | .md with YAML frontmatter |
| Cursor | AGENTS.md sections |
| GitHub Copilot | .agent.md |
| Windsurf | AGENTS.md sections |
| Codex | AGENTS.md sections |
| Gemini CLI | .md with YAML frontmatter |
| Kiro | .json |
| Amp | AGENTS.md sections |
| Roo Code | AGENTS.md sections |
Agents are automatically translated to each IDE's native format on install.
Success criteria: The command matches the user's intent and scope exactly.
Step 3: Report the result clearly
After execution, report:
- what command ran
- which agents matched or changed
- which clients/IDEs were targeted
- any next steps such as authentication, reload, or restart
When searching, present the most relevant results instead of dumping raw output.
Success criteria: The user can immediately decide what to do next.
Guardrails
- Do not run this skill proactively.
- Do not install globally unless the user asked for global scope.
- Do not remove or update agents without explicit user intent.
- Do not guess target IDE names when the user clearly cares about a specific client.
- Remember that
agentshqcan translate one source agent into multiple client formats; report that clearly.
Output Contract
Report:
- the resolved action
- project/global scope
- target IDEs or CLIs
- the agents found or changed
- any follow-up steps the user should know about