refactor: change skills position and add skill document

2026-05-28 23:09:54 +08:00
parent 0e0358a1f6
commit 617476040a
10 changed files with 180 additions and 1 deletions
@@ -1,5 +1,5 @@
 ---
-name: tianji
+name: tianji-data-query
 description: >
  Query website analytics, monitor uptime, survey results, telemetry data,
  feed events, application stats, and more from the Tianji platform via its
@@ -0,0 +1,4 @@
+{
+  "label": "Agent Skill",
+  "position": 21
+}
@@ -0,0 +1,76 @@
+---
+sidebar_position: 2
+---
+
+# Installation
+
+The skill is just three files. Any modern AI agent (Cursor, Claude Code, Codex, Copilot CLI...) already knows where its own skills directory is — so installation can be as simple as pasting one prompt.
+
+## One-Click Installation (via AI Agent)
+
+Paste the prompt below into your AI agent. It will download the files into the correct skills directory for its platform, then ask you for any missing configuration.
+
+```
+Please install the Tianji Data Query Skill into your skills directory:
+
+https://github.com/msgbyte/tianji/tree/master/skills/tianji-data-query
+
+After downloading, check whether these environment variables are set:
+  - TIANJI_BASE_URL
+  - TIANJI_API_KEY
+  - TIANJI_WORKSPACE_ID
+
+If any are missing, ask me for the values.
+```
+
+That's it. The agent picks its own skills directory, fetches the files, and prompts you for credentials when needed.
+
+## Manual Installation
+
+If you'd rather install it by hand, pick the target directory for your agent and run:
+
+```bash
+DEST="$HOME/.cursor/skills/tianji-data-query"   # or whatever your agent uses
+mkdir -p "$DEST/references"
+
+BASE="https://raw.githubusercontent.com/msgbyte/tianji/master/skills/tianji-data-query"
+curl -fSL "$BASE/SKILL.md"                          -o "$DEST/SKILL.md"
+curl -fSL "$BASE/references/api-endpoints.md"       -o "$DEST/references/api-endpoints.md"
+curl -fSL "$BASE/references/openapi-readonly.json"  -o "$DEST/references/openapi-readonly.json"
+```
+
+### Skills directory by agent
+
+| Agent | Directory |
+|-------|-----------|
+| Cursor (personal) | `~/.cursor/skills/tianji-data-query/` |
+| Cursor (project)  | `<project-root>/.cursor/skills/tianji-data-query/` |
+| Claude Code       | `~/.claude/skills/tianji-data-query/` |
+| Codex             | `~/.codex/skills/tianji-data-query/` |
+| Codex (alt)       | `~/.agents/skills/tianji-data-query/` |
+
+## Required Environment Variables
+
+The skill expects three values. Export them in your shell rc, or set them in your agent's skill config:
+
+```bash
+# Tianji instance base URL
+TIANJI_BASE_URL=https://tianji.example.com
+
+# API key for authentication
+TIANJI_API_KEY=your_api_key_here
+
+# Default workspace ID
+TIANJI_WORKSPACE_ID=your_workspace_id_here
+```
+
+### Getting an API Key
+
+1. Log in to your Tianji instance and click your **profile picture** in the top right corner.
+2. Select **Profile** from the dropdown menu.
+3. Find the **API Keys** section.
+4. Click **Create new key** and follow the prompts.
+
+## Next Steps
+
+After installation, head back to [Integration with Agent Skill](./skill.md) to see usage examples, the comparison with the MCP Server, and how the skill handles sensitive data.
@@ -0,0 +1,99 @@
+---
+sidebar_position: 1
+---
+
+# Integration with Agent Skill
+
+## Introduction
+
+The **Tianji Data Query Skill** is a lightweight, agent-agnostic skill bundle that lets AI agents (Cursor, Claude Code, Codex, Copilot CLI, etc.) query the Tianji platform directly through its read-only OpenAPI.
+
+It follows the [agentskills.io](https://agentskills.io/specification) specification — a single `SKILL.md` plus reference files. No long-running process, no extra runtime.
+
+:::tip Get started
+See the [Installation Guide](./installation.md) for one-click and manual setup.
+:::
+
+**What it covers:** 69 GET endpoints across 14 service domains:
+
+- **Website** — traffic stats, pageviews, geo distribution, Lighthouse reports
+- **Monitor** — uptime status, recent check data, monitor events
+- **Survey** — survey responses, result stats, AI categories
+- **Telemetry** — custom event counts, telemetry pageviews, metrics
+- **Feed** — channels, event streams, feed states
+- **Application** — app store reviews, app info, event stats
+- **Billing / AI Gateway / Worker / Page / Workspace / Global / AuditLog**
+
+## Skill vs MCP Server
+
+Tianji offers two ways to integrate with AI agents. Pick the one that fits your workflow:
+
+| | Agent Skill | [MCP Server](../mcp/mcp.md) |
+|--|--|--|
+| **Form** | Plain documentation files (`SKILL.md` + references) | A long-running Node.js process |
+| **Runtime** | None — agent uses `curl` or built-in HTTP tools | `npx tianji-mcp-server` |
+| **Coverage** | 69 GET endpoints (read-only, full surface) | A curated subset of tools (read + some write) |
+| **Setup** | Drop files into the agent's skills directory | Add MCP config to the agent's config file |
+| **Best for** | Cursor / Claude Code / Codex / any agent following the agentskills.io spec | Agents with first-class MCP support |
+
+You can use both at the same time without conflict.
+
+## Usage Examples
+
+Once installed, you can ask your AI agent natural-language questions and it will pick the right endpoint:
+
+### Example 1: Website traffic overview
+
+```
+User: Show me the pageviews of my main website over the past 7 days.
+
+Agent: [Calls GET /open/workspace/{workspaceId}/website/all to find the site]
+       [Then GET /open/workspace/{workspaceId}/website/{websiteId}/pageviews
+        with startAt/endAt covering 7 days]
+       Your main website received 12,438 pageviews over the past 7 days,
+       with a peak of 2,103 on Tuesday. Top referrer: google.com (43%).
+```
+
+### Example 2: Monitor health check
+
+```
+User: Are any of my monitors down right now?
+
+Agent: [Calls GET /open/workspace/{workspaceId}/monitor/all]
+       [Then GET /open/workspace/{workspaceId}/monitor/{monitorId}/status
+        for each monitor]
+       2 monitors are currently DOWN:
+       - api.example.com (HTTP 503, last UP 12 min ago)
+       - db-replica (TCP timeout, last UP 1h ago)
+       The other 8 monitors are healthy.
+```
+
+### Example 3: Survey result analysis
+
+```
+User: Summarise the responses to the "Q4 Customer Feedback" survey.
+
+Agent: [Calls GET /open/workspace/{workspaceId}/survey/all to resolve the ID]
+       [Then GET /open/workspace/{workspaceId}/survey/{surveyId}/stats]
+       [Then GET /open/workspace/{workspaceId}/survey/{surveyId}/result/list
+        with a pagination cursor]
+       "Q4 Customer Feedback" received 218 responses. Average satisfaction
+       4.3/5. Top theme: dashboard performance (mentioned 47 times). Most
+       requested feature: dark mode (31 mentions).
+```
+
+## Sensitive Data Handling
+
+Some endpoints may return platform-stored secrets (e.g. `modelApiKey`, `customModelBaseUrl` in AI Gateway responses) or PII (workspace members, audit logs, billing).
+
+The skill instructs agents to:
+
+- **Never display** `apiKey`, `modelApiKey`, `secret`, `token`, `password`, or `credential` fields.
+- **Redact or omit** these fields when summarising responses.
+- For workspace members / audit logs, only surface non-sensitive metadata (names, roles, timestamps) unless the user explicitly requests full detail.
+
+The bundled `openapi-readonly.json` also pre-redacts these fields at the schema level, so agents cannot accidentally rely on their structure.
+
+## Source
+
+The skill source lives in the Tianji repository under [`skills/tianji-data-query/`](https://github.com/msgbyte/tianji/tree/master/skills/tianji-data-query). Pull requests welcome.