Merge pull request #3 from ably/feat/debugging-with-ably-cli

feat: add debugging-with-ably-cli implicit skill

Author: umair-ably

.claude-plugin/marketplace.json

@@ -13,11 +13,12 @@
 	"plugins": [
 		{
 			"name": "ably",
-			"description": "Gives Claude expert knowledge of Ably's SDK architecture, auth patterns, and product selection - verified against live docs. Prevents common mistakes like deprecated API patterns and client-side key exposure.",
+			"description": "Expert knowledge for building and debugging with Ably — SDK patterns, auth, product selection verified against live docs, and CLI-powered diagnostics for connection, messaging, and presence issues.",
 			"source": "./",
 			"strict": false,
 			"skills": [
-				"./skills/using-ably"
+				"./skills/using-ably",
+				"./skills/debugging-with-ably-cli"
 			]
 		}
 	]

AGENTS.md

@@ -18,15 +18,20 @@ Cursor, GitHub Copilot, and other compatible agents.
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `using-ably` | Curated knowledge + code generation: product selection, SDK architecture, auth, channel design, live doc verification, post-generation checks | Any Ably-related work (always-on) |
+| `debugging-with-ably-cli` | Diagnostic decision trees, CLI capabilities, connection/channel state reference, environment-specific gotchas | Diagnosing Ably issues — messages not arriving, auth errors, connection failures, presence problems |
 
 **`using-ably`** is the primary skill — it provides the domain knowledge agents get wrong (product selection, JWT auth, Chat attach lifecycle, React client creation, etc.) and enforces fetching current docs from `ably.com/llms.txt` before generating code, with a post-generation checklist to catch common mistakes.
 
+**`debugging-with-ably-cli`** is the diagnostic skill — it teaches agents what's possible with the Ably CLI and when to use each capability for observing, simulating, and managing Ably resources during debugging.
+
 ## Skill Structure
 
 ```
 skills/
   {skill-name}/
     SKILL.md              # Skill definition (frontmatter + instructions)
+    AGENTS.md             # Optional: agent guidance for maintaining this skill
+    MAINTAINING.md        # Optional: detailed maintenance guide (referenced from AGENTS.md)
 ```
 
 ## Progressive Disclosure
@@ -39,7 +44,7 @@ Skills use a three-tier loading model to minimize context window usage:
 
 ## Key Design Principles
 
-1. **Docs-first** — Every skill fetches `https://ably.com/llms.txt` as its primary source. Web search supplements when needed.
+1. **Docs-first** — Code-generation skills fetch `https://ably.com/llms.txt` as their primary source. Web search supplements when needed. Non-code-generation skills (e.g., debugging) may rely on other sources like CLI help and error reference pages.
 2. **Product-first rule** — Never build custom infrastructure when an Ably product handles it natively.
 3. **Focus on what LLMs can't know** — Skills provide channel layout patterns, common gotchas, and design guidance — not product docs the agent can fetch itself.
 4. **Graceful degradation** — If `llms.txt` is unavailable, skills fall back to web search or browsing `ably.com/docs` directly.

README.md

@@ -9,11 +9,16 @@ Skills work with any [agentskills.io-compatible](https://agentskills.io) coding
 | Skill | Purpose | Auto-triggers when |
 |-------|---------|-------------------|
 | `using-ably` | Product selection, SDK patterns, auth, channel design, common gotchas | Any Ably-related work |
+| `debugging-with-ably-cli` | Diagnostic decision trees, CLI capabilities, state reference, environment gotchas | Diagnosing Ably issues |
 
 ### `using-ably` — Primary Knowledge Skill
 
 The core skill. Provides curated domain knowledge that agents frequently get wrong: choosing the right product/SDK, JWT vs token auth, modern v2.x patterns, Chat SDK lifecycle (attach before subscribe!), React integration pitfalls, and a production checklist.
 
+### `debugging-with-ably-cli` — CLI Debugging Skill
+
+Teaches agents what the Ably CLI can do and when to use each capability for diagnosing issues. Covers diagnostic reasoning (symptom → CLI approach), key debugging facts, connection/channel state machines, and environment-specific gotchas. Agents discover exact command syntax via `ably --help` at runtime.
+
 ## Installation
 
 ### Claude Code Plugin

skills/debugging-with-ably-cli/AGENTS.md

@@ -0,0 +1,7 @@
+# debugging-with-ably-cli
+
+Ably CLI debugging skill — teaches agents what's possible with the CLI and when to use each capability for diagnosing Ably issues.
+
+## Before making changes
+
+Read [MAINTAINING.md](./MAINTAINING.md) for design philosophy, maintenance triggers, what NOT to add, and the validation checklist. Every change to this skill should be checked against that guide.

skills/debugging-with-ably-cli/MAINTAINING.md

@@ -0,0 +1,62 @@
+# Maintaining the debugging-with-ably-cli Skill
+
+## Design Philosophy
+
+This skill teaches agents **what's possible with the Ably CLI and when to use it** — not every command, flag, and argument. The CLI is self-documenting via `--help`; agents should discover exact syntax at runtime rather than relying on this skill for command references.
+
+The skill focuses on:
+- **Categories of capability** (observe, simulate, manage, get help) — not individual commands
+- **Diagnostic reasoning** (symptom → approach) — not step-by-step procedures
+- **Domain knowledge agents lack** (state machines, persistence defaults, capability scoping, gotchas) — not documentation the CLI itself provides
+
+## Maintenance Triggers
+
+When the Ably CLI (`@ably/cli`) changes, check whether the skill needs updating:
+
+1. **New top-level command group added** (e.g., a new product like `ably liveobjects`): Add to the relevant capability section (Observe, Simulate, or Manage) and to the diagnostic decision tree if it introduces new debugging scenarios.
+
+2. **New capability within existing commands** (e.g., new flags, new subscribe targets): Usually NO skill update needed — agents discover flags via `--help`. Only update if the capability changes *what's possible* at a category level.
+
+3. **Behavioral changes** (e.g., history retention changes, new connection/channel states, new error code ranges): Update the relevant reference table (connection states, channel states, key debugging facts, environment gotchas).
+
+4. **Product changes** (e.g., new Ably product, product sunset): Update the diagnostic decision tree and capability sections.
+
+## What NOT to Add
+
+- Individual command syntax or flag listings — the CLI's `--help` handles this
+- Step-by-step procedural workflows — research shows these degrade agent performance
+- Content that duplicates the `using-ably` skill — this skill is for debugging, not building
+- Full documentation of the CLI — link to `ably --help` and let agents discover
+
+## Validation Checklist
+
+When updating, verify:
+- [ ] Skill stays under 500 lines — token budget matters, every token is loaded into agent context on every debugging session. Bloat degrades performance.
+- [ ] No command syntax is hardcoded that could go stale — capability descriptions only
+- [ ] Decision tree covers all Ably products the CLI supports
+- [ ] State reference tables match current SDK behavior
+- [ ] No overlap with `using-ably` skill content
+
+## How to Check for CLI Changes
+
+```bash
+# Check current CLI version and command groups
+ably --help
+
+# Compare against the capability categories in SKILL.md
+# Look for new top-level commands not covered
+
+# Check subcommands for each product
+ably channels --help
+ably rooms --help
+ably spaces --help
+ably logs --help
+ably bench --help
+ably integrations --help
+ably queues --help
+ably auth --help
+ably apps --help
+ably support --help
+```
+
+If a new command group appears that isn't covered in the capability sections, the skill needs updating. If only flags/options change within existing commands, no update is needed.