ai-trader-heartbeat

Poll AI-Trader heartbeat and notifications reliably through the primary pull-based mechanism.

Quality

24%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/heartbeat/SKILL.md

Quality

Discovery

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

This description is weak across most dimensions. It uses technical jargon ('pull-based mechanism', 'heartbeat') without explaining concrete actions in user-friendly terms, lacks any explicit trigger guidance ('Use when...'), and provides insufficient detail for Claude to confidently select this skill from a pool of alternatives. The only redeeming quality is the specific product name 'AI-Trader' which provides some distinctiveness.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user asks to check AI-Trader status, monitor trading bot health, or retrieve pending trading notifications.'

Replace jargon with concrete actions: instead of 'poll heartbeat and notifications through pull-based mechanism', say 'Checks AI-Trader service health status, retrieves pending trade alerts, and monitors connection reliability.'

Include natural trigger terms users might say, such as 'trading bot status', 'check if AI-Trader is running', 'trading alerts', or 'monitor trades'.

Dimension	Reasoning	Score
Specificity	The description mentions 'poll heartbeat and notifications' but these are vague actions. It doesn't specify what concrete operations are performed (e.g., check status, retrieve alerts, parse responses). 'Primary pull-based mechanism' is technical jargon that doesn't clarify capabilities.	1 / 3
Completeness	The description partially addresses 'what' (polling heartbeat and notifications) but has no explicit 'when' clause or trigger guidance. There is no 'Use when...' or equivalent statement to guide skill selection.	1 / 3
Trigger Term Quality	The terms used ('heartbeat', 'pull-based mechanism', 'notifications') are technical jargon unlikely to match natural user queries. A user would more likely say 'check AI-Trader status' or 'get trading alerts'. The product name 'AI-Trader' is specific but the surrounding terms are not natural trigger words.	1 / 3
Distinctiveness Conflict Risk	The mention of 'AI-Trader' as a specific product name provides some distinctiveness, making it unlikely to conflict with generic skills. However, 'heartbeat and notifications' could overlap with other monitoring or notification-related skills.	2 / 3
	Total	5 / 12 Passed

Implementation

42%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill provides actionable, executable code examples for heartbeat polling and WebSocket connections, which is its primary strength. However, it suffers significantly from duplication (the heartbeat section appears twice with conflicting schemas), scope creep (Discussion & Strategy APIs are beyond the stated skill purpose), and a monolithic structure with no progressive disclosure. The contradictory duplicate sections undermine trust in the content's accuracy.

Suggestions

Remove the duplicate 'Heartbeat (Pull Mode)' section and reconcile the two different request/response schemas into a single authoritative definition.

Move the Discussion & Strategy APIs, notification event schemas, and WebSocket details into separate referenced files (e.g., WEBSOCKET.md, ENDPOINTS.md) to reduce the main skill to its core polling focus.

Add validation checkpoints to the polling workflow: check HTTP status codes, handle 401/403 auth errors, and implement message ID tracking to avoid reprocessing.

Remove the Related Endpoints table or move it to a separate reference file — it lists endpoints (e.g., POST /api/claw/messages, POST /api/claw/tasks) that are never explained in this skill.

Dimension	Reasoning	Score
Conciseness	The heartbeat endpoint is duplicated verbatim in two separate sections with slightly different request/response bodies, creating confusion and wasting tokens. The WebSocket section is extensive despite being described as optional and unreliable. Notification event schemas are listed twice (once in the WebSocket section table and again as full JSON examples). Discussion & Strategy APIs and the Related Endpoints table go well beyond the stated skill scope of polling heartbeat and notifications.	1 / 3
Actionability	The skill provides fully executable Python code for both heartbeat polling and WebSocket connections, complete with correct headers, JSON payloads, and response parsing. The curl-style endpoint specifications and example request/response bodies are concrete and copy-paste ready.	3 / 3
Workflow Clarity	The polling workflow is clear with recommended intervals and a working async loop with error handling. However, there are no validation checkpoints (e.g., verifying the response status code, handling auth failures, or confirming message acknowledgment), and the duplicate heartbeat sections with different request/response schemas create ambiguity about which is correct.	2 / 3
Progressive Disclosure	The content is a monolithic wall of text with no references to external files. The Discussion & Strategy APIs, notification event schemas, and WebSocket details could all be split into separate reference files. There is no bundle structure to support progressive disclosure, and the document tries to cover everything inline.	1 / 3
	Total	7 / 12 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: HKUDS/AI-Trader
Commit: dcdccb2

Reviewed: 10 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.