@tplog/pi-zendy 0.2.17 → 0.3.0

package/skills/zendesk-kg/SKILL.md

@@ -1,120 +0,0 @@
----
-name: zendesk-kg
-description: "Search the Zendesk Knowledge Graph via the `zendesk-kg` CLI. Hybrid (vector + fulltext) retrieval over historical tickets — use for cross-ticket / semantic lookups that go beyond `zcli` single-ticket fetch."
----
-
-# zendesk-kg
-
-`zendesk-kg` is a CLI for the Zendesk Knowledge Graph retrieval API. It performs **hybrid search (vector + fulltext) with Reciprocal Rank Fusion** over an index of historical Dify Enterprise support tickets — each ticket pre-summarized into `quickSummary` / `issueSummary` / `solutionSummary`. Use it when you need to find **similar past issues, related conversations, or aggregated knowledge** that a single-ticket lookup can't surface.
-
-## When to use this skill
-
-- The user is investigating a recurring symptom and you want to find **other tickets that show the same pattern**
-- You need cross-ticket evidence ("has anyone else hit this?") to support a hypothesis
-- You want to retrieve related KB-style ticket summaries before drafting a reply
-
-## When NOT to use
-
-- The user gave you a specific ticket ID — use `zcli <id>` + `zcli comments <id>`. zendesk-kg returns curated *summaries*, not the raw ticket / comment thread.
-- The question is answerable from Helm chart values or source code — use `helm-watchdog` or `source-check` first.
-
-## Quick start
-
-```bash
-zendesk-kg --help
-zendesk-kg search --help     # has the most options worth knowing
-```
-
-## Install (if missing)
-
-The standard `zendy` install handles this automatically. To install manually:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/sorphwer/zendesk-kg-cli-release/main/install.sh | sh
-zendesk-kg init   # paste your RETRIEVER_API_KEY
-```
-
-Config lives in `~/.zendesk-kg/.env` (`RETRIEVER_API_KEY`, `RETRIEVER_API_URL`).
-
-## Core commands
-
-| Command | Purpose |
-|---|---|
-| `zendesk-kg search "<query>" [flags]` | Hybrid search. Natural-language query. |
-| `zendesk-kg stats` | Show current index size / coverage. |
-| `zendesk-kg health` | Check API connectivity. **Currently unreliable — see Caveats below.** |
-| `zendesk-kg init` | Re-enter API key / URL. Setup only. |
-| `zendesk-kg set-env output json` | Set default output format. |
-| `zendesk-kg update` | Self-update the CLI binary. Don't run proactively. |
-
-## `search` flags worth knowing
-
-```
--k, --top-k INTEGER     Number of results to return (1-20, default 5)
--s, --order-by TEXT     rrfScore | createdAt | priority
--o, --output FORMAT     table | json | text
-    --priority TEXT     Filter: high / normal / low / urgent
--v, --version TEXT      Filter by Dify version mentioned in the ticket
-    --created-after DATE
-    --use-llm           LLM-formatted summary instead of raw JSON
-```
-
-For agent automation always use `-o json`. `table` is for humans, `text` is for terminal browsing.
-
-## Output format (real shape, not pseudocode)
-
-`search -o json` returns:
-
-```json
-{
-  "results": [
-    {
-      "ticketId": "765",
-      "subject": "<original ticket subject, often non-English>",
-      "status": "closed | open | pending | ...",
-      "priority": "low | normal | high | urgent",
-      "quickSummary": "1-2 sentence summary in English",
-      "issueSummary": "Multi-paragraph: Environment / Symptoms / User Questions / Timeline",
-      "solutionSummary": "Multi-paragraph: Analysis / Actions / Recommendations / Resolution",
-      "createdAt": "YYYY-MM-DD HH:MM:SS",
-      "handledBy": ["agent_name", ...],
-      "versions": ["3.8.0", ...],
-      "keywords": ["sso", "oidc", ...],
-      "referenceUrls": [...],
-      "channels": { ... }
-    },
-    ...
-  ]
-}
-```
-
-**Always surface `ticketId`, `quickSummary`, and `solutionSummary`** when reporting back to the user. The FDE will follow up on the ticket via `zcli <ticketId>` for full context. Don't dump the whole JSON.
-
-## Behavioral rules the agent must follow
-
-- **Use natural-language queries.** Describe the symptom in the user's words; the graph handles semantics. Don't manually OR a bunch of keywords.
-- **Cite ticket IDs.** When summarizing for the user, always include the ticket IDs the synthesis is drawn from — the FDE will want to read the originals.
-- **`search` returns curated summaries, not raw tickets.** For raw comment threads, follow up with `zcli <id>` + `zcli comments <id>`.
-- **Filter when you can.** If the user mentioned a Dify version (`-v 3.8.0`) or priority (`--priority high`), use the flag — don't filter post-hoc on the JSON.
-- **Don't assume coverage.** The KG is indexed over a snapshot, not live Zendesk. Empty result ≠ proof nothing exists. Fall back to `zcli search` for live data.
-- **Don't run `update` without explicit user request.** Self-update mutates the binary on disk.
-
-## Typical retrieval flow
-
-```bash
-# 1. Cast a wide semantic net for context (most-relevant first by default)
-zendesk-kg search "users intermittently logged out after SSO with MFA enabled" -k 5 -o json
-
-# 2. Inspect the most relevant ticket end-to-end via zcli
-zcli <ticketId>
-zcli comments <ticketId>
-
-# 3. Cross-check Helm config / source as needed
-# (helm-watchdog, source-check skills)
-```
-
-## Caveats
-
-- **`health` and `stats` may report `Redirecting...` / `unreachable` even when `search` works.** As of zendesk-kg 0.1.2 / retriever backend v0.1, those endpoints sit behind a 302 redirect to a login page while `/search` is API-key-authenticated directly. **Don't gate retries on `health`** — if `search` failed and you want to diagnose, retry `search` itself or surface the error verbatim to the user. Treat `health: ok` as a real signal, but `health: unreachable` as inconclusive.
-- **Errors come back in the JSON body, not via exit code.** All commands tend to exit 0 even when the API rejects the request. Always parse `stdout` for `"error"` / `"status": "unreachable"` instead of relying on `$?`.
-- **Index is a snapshot.** The catalog won't include tickets that opened today; for fresh tickets use `zcli search`.