How do I install the Lingtai Doctor skill?

Run npx get-skill add lingtai-ai/lingtai-doctor 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 Lingtai Doctor safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: executes scripts, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Lingtai Doctor?

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 Lingtai Doctor free to use?

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

Who published Lingtai Doctor?

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

Lingtai Doctor by lingtai-ai — Agent Skill

Name: Lingtai Doctor
Author: lingtai-ai

Lingtai Doctor

Read-only health diagnostics when an agent looks dead but the evidence is mixed, or a migration may have left stale MCP/addon paths; run before deciding to mail, refresh, CPR, or edit persistent configuration. Includes a bundled read-only `doctor.py`.

lingtai-ai Updated Nov 11, 2026

File contents

LingTai Doctor

lingtai-doctor is the first stop when a LingTai agent or bot looks dead but the evidence is mixed: Telegram/Feishu/WeChat cannot reach it, the TUI says it is offline, a heartbeat is fresh, MCP configuration points at an old runtime, or logs/notifications/status files disagree.

Diagnosis before repair. The bundled script is read-only: it summarizes local evidence, redacts secrets, and suggests next steps. It never edits init.json, touches mailboxes, refreshes agents, or kills processes. Repairs belong to the owning manuals routed below.

Run it

# From a source checkout, against any agent workdir:
python3 src/lingtai/intrinsic_skills/lingtai-doctor/scripts/doctor.py \
  --agent-dir /path/to/project/.lingtai/mimo-1

# From inside an agent (installed bundle); --agent-dir defaults to $LINGTAI_AGENT_DIR:
python3 .library/intrinsic/capabilities/lingtai-doctor/scripts/doctor.py

# Add --json for machine-readable output, or --self-test for a packaging check.

What it checks

Layered so one broken surface is not mistaken for a dead agent:

Identity / lifecycle files — .agent.json, .status.json, and .agent.heartbeat freshness.
Process evidence — best-effort ps scan for lingtai-agent run <agent-dir> / python -m lingtai run <agent-dir>.
Notifications and logs — channel files plus common logs such as logs/events.jsonl, logs/agent.log, and token ledgers, by mtime/size only.
Internal mail footprint — inbox/outbox counts without message bodies.
MCP/addon configuration — init.json top-level mcp entries and mcp_registry.jsonl stdio commands, checked for existence and executability (or PATH resolution). Environment values are redacted; only path-like existence facts are reported.
Migration drift hints — stale Linux /home/... paths on macOS-style hosts, stale macOS /Users/... paths on Linux-style hosts, and likely ~/.lingtai-tui/runtime/venv/bin/python replacements.
First-party MCP server imports — if a configured stdio command points at a usable Python executable, tries importing the configured LingTai curated MCP modules (lingtai.mcp_servers. telegram/feishu/wechat/whatsapp/imap/cloud_mail) without reading credentials.

Reading the result

Top-level severity is OK (no obvious local mismatch), WARN (at least one surface looks stale, missing, or inconsistent), or FAIL (a critical local file/config/path is missing or broken).

Triage in this order, then follow the owning manual rather than improvising a repair:

Doctor evidence	Do	Owner
`.agent.heartbeat` is fresh	The agent is probably alive; internal email should wake it even if an external addon is broken.	`email-manual`
Heartbeat and process are both dead	CPR may be appropriate. If the process is alive but status/logs are stale, investigate before CPR.	`substrate-manual`
An MCP stdio command points at a missing runtime	Back up `init.json` and `mcp_registry.jsonl` first, then replace the stale command path and refresh the agent.	`mcp-manual` troubleshooting
Notifications are stale while the agent is healthy	Handle it through the producer tool; notification delivery is one-shot, never clears producer state, and there is no generic dismiss action, so an old record that is not re-delivered is not a fault.	`notification-manual` delivery safety

Scope

Doctor is the shared diagnostic foundation and covers the whole agent footprint, not only MCP registry syntax — plugin(mode="mcp", action="info") validates the registry, not lifecycle, process, log, or mail evidence. TUI /doctor should call these scripts instead of maintaining a separate copy of the logic.

---name: lingtai-doctordescription: > Read-only health diagnostics when an agent looks dead but the evidence is mixed, or a migration may have left stale MCP/addon paths; run before deciding to mail, refresh, CPR, or edit persistent configuration. Includes a bundled read-only `doctor.py`.version: 0.2.0tags: [doctor, diagnostics, mcp, addons, heartbeat, migration, recovery]last_changed_at: "2026-08-07T00:00:00Z"related_files:- src/lingtai/intrinsic_skills/lingtai-doctor/scripts/doctor.pymaintenance: | Tracks the tool/capability behavior it teaches; update when that tool's behavior changes.metadata: source: https://skillmd.com/skills/lingtai-ai/lingtai-doctor---# LingTai Doctor`lingtai-doctor` is the first stop when a LingTai agent or bot looks dead butthe evidence is mixed: Telegram/Feishu/WeChat cannot reach it, the TUI says itis offline, a heartbeat is fresh, MCP configuration points at an old runtime, orlogs/notifications/status files disagree.**Diagnosis before repair.** The bundled script is read-only: it summarizes localevidence, redacts secrets, and suggests next steps. It never edits `init.json`,touches mailboxes, refreshes agents, or kills processes. Repairs belong to theowning manuals routed below.## Run it```bash# From a source checkout, against any agent workdir:python3 src/lingtai/intrinsic_skills/lingtai-doctor/scripts/doctor.py \ --agent-dir /path/to/project/.lingtai/mimo-1# From inside an agent (installed bundle); --agent-dir defaults to $LINGTAI_AGENT_DIR:python3 .library/intrinsic/capabilities/lingtai-doctor/scripts/doctor.py# Add --json for machine-readable output, or --self-test for a packaging check.```## What it checksLayered so one broken surface is not mistaken for a dead agent:1. **Identity / lifecycle files** — `.agent.json`, `.status.json`, and `.agent.heartbeat` freshness.2. **Process evidence** — best-effort `ps` scan for `lingtai-agent run <agent-dir>` / `python -m lingtai run <agent-dir>`.3. **Notifications and logs** — channel files plus common logs such as `logs/events.jsonl`, `logs/agent.log`, and token ledgers, by mtime/size only.4. **Internal mail footprint** — inbox/outbox counts without message bodies.5. **MCP/addon configuration** — `init.json` top-level `mcp` entries and `mcp_registry.jsonl` stdio commands, checked for existence and executability (or `PATH` resolution). Environment values are redacted; only path-like existence facts are reported.6. **Migration drift hints** — stale Linux `/home/...` paths on macOS-style hosts, stale macOS `/Users/...` paths on Linux-style hosts, and likely `~/.lingtai-tui/runtime/venv/bin/python` replacements.7. **First-party MCP server imports** — if a configured stdio command points at a usable Python executable, tries importing the configured LingTai curated MCP modules (`lingtai.mcp_servers.` `telegram`/`feishu`/`wechat`/`whatsapp`/`imap`/`cloud_mail`) without reading credentials.## Reading the resultTop-level severity is **OK** (no obvious local mismatch), **WARN** (at least onesurface looks stale, missing, or inconsistent), or **FAIL** (a critical localfile/config/path is missing or broken).Triage in this order,then follow the owning manual rather than improvising a repair:| Doctor evidence | Do | Owner ||---|---|---|| `.agent.heartbeat` is fresh | The agent is probably alive; internal email should wake it even if an external addon is broken. | [`email-manual`](../../tools/email/manual/SKILL.md) || Heartbeat and process are both dead | CPR may be appropriate. If the process is alive but status/logs are stale, investigate before CPR. | [`substrate-manual`](../system-manual/reference/substrate-manual/SKILL.md) || An MCP stdio command points at a missing runtime | **Back up `init.json` and `mcp_registry.jsonl` first**, then replace the stale command path and refresh the agent. | [`mcp-manual` troubleshooting](../../tools/mcp/skills/mcp-manual/reference/troubleshooting.md) || Notifications are stale while the agent is healthy | Handle it through the producer tool; notification delivery is one-shot, never clears producer state, and there is no generic dismiss action, so an old record that is not re-delivered is not a fault. | [`notification-manual` delivery safety](../../tools/notification/manual/reference/dismissal-safety/SKILL.md) |## ScopeDoctor is the shared diagnostic foundation and covers the whole agent footprint,not only MCP registry syntax — `plugin(mode="mcp", action="info")` validates the registry, notlifecycle, process, log, or mail evidence. TUI `/doctor` should call thesescripts instead of maintaining a separate copy of the logic.

Frequently asked questions