Skip to main content
The init command installs the ap-query skill template into your coding agent’s skill directory, enabling agents to profile and analyze Java applications autonomously.

​
Usage

ap-query init [flags]

​
What it does

The init command:
  1. Detects or downloads async-profiler - Finds asprof on your system or offers to download it
  2. Renders the skill template - Embeds ap-query and asprof paths into the skill file
  3. Installs to agent directory - Writes SKILL.md to your agent’s skill location
After installation, agents can automatically profile applications and analyze results when prompted.

​
Installation modes

Install for all projects: 
ap-query init
Agent-specific global install: 
ap-query init --claude    # Claude Code only
ap-query init --codex     # Codex only
Claude: Installs to ~/.claude/skills/jfr/SKILL.md
Codex: Installs to ~/.codex/skills/jfr/SKILL.md (or $CODEX_HOME)

​
Project-local installation

Install for the current project only: 
ap-query init --project
Agent-specific project install: 
ap-query init --project --claude    # Claude Code
ap-query init --project --codex     # Codex
Claude: Installs to .claude/skills/jfr/SKILL.md
Codex: Installs to .agents/skills/jfr/SKILL.md

​
Flags

​
--asprof
string
Explicit path to asprof binary. Skips auto-detection and interactive prompt.
ap-query init --asprof /usr/local/bin/asprof
​
--project
boolean
default:false
Install to current directory instead of home directory.
ap-query init --project
​
--force
boolean
default:false
Overwrite existing skill files without prompting.
ap-query init --force
​
--claude
boolean
default:false
Install only for Claude Code (.claude/skills/jfr/).
​
--codex
boolean
default:false
Install only for Codex (.codex/skills/jfr/ global, .agents/skills/jfr/ project).
​
--stdout
boolean
default:false
Dump rendered skill to stdout instead of installing. Useful for piping into custom agents.
ap-query init --stdout > my-agent/skills/profiling.md

​
async-profiler detection

The init command attempts to find asprof in this order:
  1. Explicit --asprof flag - Use the provided path
  2. PATH search - Look for asprof in $PATH
  3. Common locations - Check /usr/local/bin, ~/.ap-query/, etc.
  4. Interactive download - Offer to download async-profiler to ~/.ap-query/
If async-profiler is not found and you decline the download, init will still create the skill but agents won’t be able to profile until you install async-profiler manually.

​
Examples

​
Standard setup

Install for both Claude Code and Codex globally: 
ap-query init

​
Project-specific setup

Install for this project only (commits .claude/ or .agents/ to version control): 
ap-query init --project

​
Custom async-profiler location

Specify async-profiler path explicitly: 
ap-query init --asprof /opt/async-profiler/bin/asprof

​
Preview skill content

Print the rendered skill without installing: 
ap-query init --stdout

​
Force reinstall

Overwrite existing skill (useful after updating ap-query): 
ap-query init --force

​
Updating skills

After running ap-query update to upgrade the binary, skills are automatically regenerated if they were previously installed globally. For project-local skills, re-run ap-query init --project --force to update them.

​
Agent usage

Once installed, ask your agent: 
Profile this Java application with async-profiler and analyze the results.
Start with hotspot triage, then drill down and report concrete next actions.
The agent will:
  • Identify the Java process
  • Profile with asprof
  • Analyze with ap-query info, hot, tree, trace, etc.
  • Provide actionable optimization recommendations

​
Troubleshooting

Some agents auto-activate skills based on context (e.g., profiling keywords). If not, explicitly mention “use ap-query” or “analyze with the profiling skill.”
Check directory permissions for ~/.claude/ or ~/.codex/. Create manually if needed:
mkdir -p ~/.claude/skills/jfr
ap-query init --force
After updating ap-query, force reinstall:
ap-query init --force
Restart your agent if it caches skills.

​
See also

Build docs developers (and LLMs) love

Get started for freeTalk to us