How do I install the Iterm Diagnostics skill?

Run npx skillmds@latest add antonio-mello-ai/iterm-diagnostics in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Iterm Diagnostics safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Iterm Diagnostics?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Iterm Diagnostics free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Iterm Diagnostics?

antonio-mello-ai (@antonio-mello-ai) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Iterm Diagnostics by antonio-mello-ai

Name: Iterm Diagnostics
Rating: 4.2 (5 reviews)
Author: antonio-mello-ai

Iterm Diagnostics

Run support-safe iTerm diagnostics. Use when iTerm agent control, AppleScript, pane targeting, badges, screenshots, permissions, or layout automation is not working, or when the user asks for an iTerm health check.

File contents

iTerm Diagnostics

Use this skill to collect a read-only health report for iTerm automation. Do not dump shell history, environment variables, prompts, tokens, or command output from panes.

Quick Report

skills/iterm-diagnostics/scripts/iterm-diagnostics

Use context only when the issue depends on pane identity:

skills/iterm-diagnostics/scripts/iterm-diagnostics --include-context

Run a visible badge test only when the user is ready for a small UI change:

skills/iterm-diagnostics/scripts/iterm-diagnostics --test-badge "diag"

What It Checks

osascript is available.
iTerm responds as com.googlecode.iterm2.
The current iTerm session can be read.
Windows, tabs, sessions, names, and TTYs can be enumerated.
Caller/current target resolution works.
Optional badge test can write an OSC 1337 badge to the current session.

Interpretation

iterm_bundle fails: iTerm is missing, renamed, or AppleScript cannot resolve it.
current_session fails: iTerm is closed, has no windows, or Automation permission is blocked.
list_sessions fails: AppleScript access is blocked or the iTerm scripting dictionary changed.
identify reports caller-fallback-current: the agent runtime has no TTY, so targeting is based on the current iTerm focus.
Screenshot failures usually point to macOS Screen Recording permission.

Rules

Stay read-only unless the user asked for a visible test.
Do not include pane contents in reports.
Use --include-context only when session names and TTYs are needed.
After changing permissions or fixing a helper script, rerun the diagnostic and report changed checks.

Reference

references/permissions.md lists the macOS permissions involved.

---name: iterm-diagnosticsdescription: Run support-safe iTerm diagnostics. Use when iTerm agent control, AppleScript, pane targeting, badges, screenshots, permissions, or layout automation is not working, or when the user asks for an iTerm health check.---# iTerm DiagnosticsUse this skill to collect a read-only health report for iTerm automation. Do notdump shell history, environment variables, prompts, tokens, or command outputfrom panes.## Quick Report```bashskills/iterm-diagnostics/scripts/iterm-diagnostics```Use context only when the issue depends on pane identity:```bashskills/iterm-diagnostics/scripts/iterm-diagnostics --include-context```Run a visible badge test only when the user is ready for a small UI change:```bashskills/iterm-diagnostics/scripts/iterm-diagnostics --test-badge "diag"```## What It Checks- `osascript` is available.- iTerm responds as `com.googlecode.iterm2`.- The current iTerm session can be read.- Windows, tabs, sessions, names, and TTYs can be enumerated.- Caller/current target resolution works.- Optional badge test can write an OSC 1337 badge to the current session.## Interpretation- `iterm_bundle` fails: iTerm is missing, renamed, or AppleScript cannot resolve it.- `current_session` fails: iTerm is closed, has no windows, or Automation permission is blocked.- `list_sessions` fails: AppleScript access is blocked or the iTerm scripting dictionary changed.- `identify` reports `caller-fallback-current`: the agent runtime has no TTY, so targeting is based on the current iTerm focus.- Screenshot failures usually point to macOS Screen Recording permission.## Rules- Stay read-only unless the user asked for a visible test.- Do not include pane contents in reports.- Use `--include-context` only when session names and TTYs are needed.- After changing permissions or fixing a helper script, rerun the diagnostic and report changed checks.## Reference- [references/permissions.md](references/permissions.md) lists the macOS permissions involved.

Frequently asked questions