agent-health

Name: agent-health
Author: tranhieutt

69stars41forks

How to install agent-health?

tranhieutt/software_development_department/agent-health

$npx -y skills add tranhieutt/software_development_department --skill agent-health

Installs into the current project.

Summary

Reads production/traces/agent-metrics.jsonl and displays a per-agent performance summary table for the current or a specified session. Highlights agents with high error rates or OPEN circuit breaker state.

Files · 1

View on GitHub

SKILL.md

1	# Agent Health
2
3	Display a performance summary table from `production/traces/agent-metrics.jsonl`,
4	cross-referenced with `production/session-state/circuit-state.json` for live
5	circuit breaker states.
6
7	## Steps
8
9	### 1. Parse arguments
10
11	\| Flag \| Default \| Description \|
12	\| :--- \| :--- \| :--- \|
13	\| `--session <branch>` \| current branch \| Filter entries by `session` field \|
14	\| `--agent <name>` \| all \| Show only this agent \|
15	\| `--since <date>` \| no limit \| Only entries with `date >= YYYY-MM-DD` \|
16	\| `--log` \| false \| If set, append a fresh metrics snapshot to `agent-metrics.jsonl` \|
17
18	Get current branch: `git branch --show-current`.
19
20	### 2. Read data sources
21
22	Read both files in parallel:
23
24	- `production/traces/agent-metrics.jsonl` — historical metrics per agent per session
25	- `production/session-state/circuit-state.json` — live circuit breaker states
26
27	If `agent-metrics.jsonl` contains only the schema header line (no actual entries):
28
29	```text
30	📭 No agent metrics recorded yet for this session.
31	Metrics are written when agents use /agent-health --log
32	or at the end of a session via /save-state.
33
34	Circuit breaker states (live):
35	[show table from circuit-state.json only]
36	```
37
38	### 3. Aggregate metrics
39
40	For each agent, compute across the filtered entries:
41
42	- `total_tasks` = `tasks_completed` + `tasks_failed` + `tasks_blocked`
43	- `success_rate` = `tasks_completed / total_tasks * 100` (0 if no tasks)
44	- `error_rate` = latest `error_rate` field value
45	- `circuit_state` = from `circuit-state.json` (live, not from log)
46
47	### 4. Render health table
48
49	```text
50	🏥 Agent Health Report — session: <branch> · <date range>
51	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
52
53	Agent Tasks ✅ Done ❌ Failed ⛔ Blocked Success% Circuit
54	──────────────────────────────────────────────────────────────────────────────
55	backend-developer 8 7 1 0 87.5% 🟢 CLOSED
56	frontend-developer 5 5 0 0 100.0% 🟢 CLOSED
57	qa-engineer 6 4 2 0 66.7% 🟡 HALF-OPEN
58	data-engineer 2 2 0 0 100.0% 🟢 CLOSED
59	diagnostics 1 0 1 0 0.0% 🔴 OPEN
60	──────────────────────────────────────────────────────────────────────────────
61	TOTAL 22 18 4 0 81.8%
62
63	⚠️ Agents needing attention:
64	🔴 diagnostics — Circuit OPEN · fallback: surface to user
65	🟡 qa-engineer — Circuit HALF-OPEN · 2 failures this session
66	```
67
68	Circuit state icons:
69	- `🟢 CLOSED` — healthy
70	- `🟡 HALF-OPEN` — recovering, monitor closely
71	- `🔴 OPEN` — bypassed, routed to fallback
72
73	Flag agents as needing attention if:
74	- `circuit_state` is `OPEN` or `HALF-OPEN`
75	- `success_rate` < 70%
76	- `tasks_failed` >= 2
77
78	### 5. Log snapshot (if --log)
79
80	If `--log` flag was passed, append one entry per active agent to
81	`production/traces/agent-metrics.jsonl`:
82
83	```jsonl
84	{"date":"<YYYY-MM-DD>","session":"<branch>","agent":"<agent>","tasks_completed":<N>,"tasks_failed":<N>,"tasks_blocked":<N>,"avg_tokens_est":<N>,"error_rate":<0.0-1.0>,"circuit_state":"CLOSED\|OPEN\|HALF-OPEN","notes":"<optional>"}
85	```
86
87	Get `circuit_state` from `circuit-state.json`. Estimate `avg_tokens_est` from
88	decision ledger entry count × 800 tokens (rough estimate per entry) if no exact
89	token data is available. Note this is an estimate and mark with `_est` suffix.
90
91	Print after logging:
92
93	```text
94	✅ Metrics snapshot logged → production/traces/agent-metrics.jsonl
95	[N] agents recorded · <date>
96	```
97
98	### 6. Suggest actions
99
100	After the table, if any agents need attention:
101
102	```text
103	💡 Suggested actions:
104	• /resume-from <task_id> — recover failed task checkpoint
105	• /trace-history --risk High — audit high-risk decisions
106	• Check circuit-state.json — update OPEN agents once issue resolved
107	```
108
109	---
110
111	## How metrics get into the file
112
113	Agents append entries in two ways:
114
115	1. Manual: Run `/agent-health --log` at end of session
116	2. Via `/save-state`: When saving state with a `task_id`, metrics for the
117	active agent are appended automatically
118
119	The file grows one JSON line per agent per session. Use `--since` to filter
120	to recent sessions and avoid reading stale data from weeks ago.
121
122	---
123
124	## Quick examples
125
126	```bash
127	# Summary for current session
128	/agent-health
129
130	# Check one agen

People who liked this also viewed

6 picks

Type

agent-health

69stars41forks

View on GitHub

How to install agent-health?

tranhieutt/software_development_department/agent-health

$npx -y skills add tranhieutt/software_development_department --skill agent-health

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Agent Health
2
3	Display a performance summary table from `production/traces/agent-metrics.jsonl`,
4	cross-referenced with `production/session-state/circuit-state.json` for live
5	circuit breaker states.
6
7	## Steps
8
9	### 1. Parse arguments
10
11	\| Flag \| Default \| Description \|
12	\| :--- \| :--- \| :--- \|
13	\| `--session <branch>` \| current branch \| Filter entries by `session` field \|
14	\| `--agent <name>` \| all \| Show only this agent \|
15	\| `--since <date>` \| no limit \| Only entries with `date >= YYYY-MM-DD` \|
16	\| `--log` \| false \| If set, append a fresh metrics snapshot to `agent-metrics.jsonl` \|
17
18	Get current branch: `git branch --show-current`.
19
20	### 2. Read data sources
21
22	Read both files in parallel:
23
24	- `production/traces/agent-metrics.jsonl` — historical metrics per agent per session
25	- `production/session-state/circuit-state.json` — live circuit breaker states
26
27	If `agent-metrics.jsonl` contains only the schema header line (no actual entries):
28
29	```text
30	📭 No agent metrics recorded yet for this session.
31	Metrics are written when agents use /agent-health --log
32	or at the end of a session via /save-state.
33
34	Circuit breaker states (live):
35	[show table from circuit-state.json only]
36	```
37
38	### 3. Aggregate metrics
39
40	For each agent, compute across the filtered entries:
41
42	- `total_tasks` = `tasks_completed` + `tasks_failed` + `tasks_blocked`
43	- `success_rate` = `tasks_completed / total_tasks * 100` (0 if no tasks)
44	- `error_rate` = latest `error_rate` field value
45	- `circuit_state` = from `circuit-state.json` (live, not from log)
46
47	### 4. Render health table
48
49	```text
50	🏥 Agent Health Report — session: <branch> · <date range>
51	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
52
53	Agent Tasks ✅ Done ❌ Failed ⛔ Blocked Success% Circuit
54	──────────────────────────────────────────────────────────────────────────────
55	backend-developer 8 7 1 0 87.5% 🟢 CLOSED
56	frontend-developer 5 5 0 0 100.0% 🟢 CLOSED
57	qa-engineer 6 4 2 0 66.7% 🟡 HALF-OPEN
58	data-engineer 2 2 0 0 100.0% 🟢 CLOSED
59	diagnostics 1 0 1 0 0.0% 🔴 OPEN
60	──────────────────────────────────────────────────────────────────────────────
61	TOTAL 22 18 4 0 81.8%
62
63	⚠️ Agents needing attention:
64	🔴 diagnostics — Circuit OPEN · fallback: surface to user
65	🟡 qa-engineer — Circuit HALF-OPEN · 2 failures this session
66	```
67
68	Circuit state icons:
69	- `🟢 CLOSED` — healthy
70	- `🟡 HALF-OPEN` — recovering, monitor closely
71	- `🔴 OPEN` — bypassed, routed to fallback
72
73	Flag agents as needing attention if:
74	- `circuit_state` is `OPEN` or `HALF-OPEN`
75	- `success_rate` < 70%
76	- `tasks_failed` >= 2
77
78	### 5. Log snapshot (if --log)
79
80	If `--log` flag was passed, append one entry per active agent to
81	`production/traces/agent-metrics.jsonl`:
82
83	```jsonl
84	{"date":"<YYYY-MM-DD>","session":"<branch>","agent":"<agent>","tasks_completed":<N>,"tasks_failed":<N>,"tasks_blocked":<N>,"avg_tokens_est":<N>,"error_rate":<0.0-1.0>,"circuit_state":"CLOSED\|OPEN\|HALF-OPEN","notes":"<optional>"}
85	```
86
87	Get `circuit_state` from `circuit-state.json`. Estimate `avg_tokens_est` from
88	decision ledger entry count × 800 tokens (rough estimate per entry) if no exact
89	token data is available. Note this is an estimate and mark with `_est` suffix.
90
91	Print after logging:
92
93	```text
94	✅ Metrics snapshot logged → production/traces/agent-metrics.jsonl
95	[N] agents recorded · <date>
96	```
97
98	### 6. Suggest actions
99
100	After the table, if any agents need attention:
101
102	```text
103	💡 Suggested actions:
104	• /resume-from <task_id> — recover failed task checkpoint
105	• /trace-history --risk High — audit high-risk decisions
106	• Check circuit-state.json — update OPEN agents once issue resolved
107	```
108
109	---
110
111	## How metrics get into the file
112
113	Agents append entries in two ways:
114
115	1. Manual: Run `/agent-health --log` at end of session
116	2. Via `/save-state`: When saving state with a `task_id`, metrics for the
117	active agent are appended automatically
118
119	The file grows one JSON line per agent per session. Use `--since` to filter
120	to recent sessions and avoid reading stale data from weeks ago.
121
122	---
123
124	## Quick examples
125
126	```bash
127	# Summary for current session
128	/agent-health
129
130	# Check one agen

People who liked this also viewed

6 picks

Type