find-agents

This skill changes the user's agent inventory and must stay explicit-user-only.

Non-negotiable rules:

1. Verify agentshq availability before relying on it.
2. Be explicit about scope: project vs global, specific IDEs vs auto-detect.
3. Do not install or remove agents the user did not ask for.
4. Confirm ambiguous install targets before making changes.
5. Report exactly what was added, removed, or updated.

Find Agents

Inputs

• $request: Search terms, repo source, or management intent such as list, remove, or update

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

When installing, respect:

• explicit --ide ... choices when the user gave them
• -g only when the user asked for global scope
• --list when the user wants to inspect a source before installing

Supported IDEs

The CLI supports 43+ IDEs. Common ones:

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 agentshq can translate one source agent into multiple client formats; report that clearly.

Output Contract

Report:

1. the resolved action
2. project/global scope
3. target IDEs or CLIs
4. the agents found or changed
5. any follow-up steps the user should know about