@mohammadhprp/system-prompt 0.11.1 → 0.11.2

package/framework/skills/sentry/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: sentry
+description: Inspect Sentry issues, summarize production errors, and pull health data via the Sentry API (read-only). Use when user says "check Sentry", "what errors in production?", "summarize Sentry issues", "recent crashes", or "production error report". Requires SENTRY_AUTH_TOKEN. Do NOT use for setting up Sentry SDK, configuring alerts, or non-Sentry error monitoring.
+metadata:
+  author: github.com/openai/skills
+  version: '1.0.0'
+---
+
+# Sentry (Read-only Observability)
+
+## Quick start
+
+- If not already authenticated, ask the user to provide a valid `SENTRY_AUTH_TOKEN` (read-only scopes such as `project:read`, `event:read`) or to log in and create one before running commands.
+- Set `SENTRY_AUTH_TOKEN` as an env var.
+- Optional defaults: `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_BASE_URL`.
+- Defaults: org/project `{your-org}`/`{your-project}`, time range `24h`, environment `prod`, limit 20 (max 50).
+- Always call the Sentry API (no heuristics, no caching).
+
+If the token is missing, give the user these steps:
+
+1. Create a Sentry auth token: <https://sentry.io/settings/account/api/auth-tokens/>
+2. Create a token with read-only scopes such as `project:read`, `event:read`, and `org:read`.
+3. Set `SENTRY_AUTH_TOKEN` as an environment variable in their system.
+4. Offer to guide them through setting the environment variable for their OS/shell if needed.
+
+- Never ask the user to paste the full token in chat. Ask them to set it locally and confirm when ready.
+
+## Core tasks (use bundled script)
+
+Use `scripts/sentry_api.py` for deterministic API calls. It handles pagination and retries once on transient errors.
+
+## Skill path (set once)
+
+```bash
+export AGENT_SKILLS_HOME="${AGENT_SKILLS_HOME:-$HOME/.agent-skills}"
+export SENTRY_API="$AGENT_SKILLS_HOME/skills/sentry/scripts/sentry_api.py"
+```
+
+User-scoped skills install under `$AGENT_SKILLS_HOME/skills` (default: `~/.agent-skills/skills`).
+
+### 1) List issues (ordered by most recent)
+
+```bash
+python3 "$SENTRY_API" \
+  list-issues \
+  --org {your-org} \
+  --project {your-project} \
+  --environment prod \
+  --time-range 24h \
+  --limit 20 \
+  --query "is:unresolved"
+```
+
+### 2) Resolve an issue short ID to issue ID
+
+```bash
+python3 "$SENTRY_API" \
+  list-issues \
+  --org {your-org} \
+  --project {your-project} \
+  --query "ABC-123" \
+  --limit 1
+```
+
+Use the returned `id` for issue detail or events.
+
+### 3) Issue detail
+
+```bash
+python3 "$SENTRY_API" \
+  issue-detail \
+  1234567890
+```
+
+### 4) Issue events
+
+```bash
+python3 "$SENTRY_API" \
+  issue-events \
+  1234567890 \
+  --limit 20
+```
+
+### 5) Event detail (no stack traces by default)
+
+```bash
+python3 "$SENTRY_API" \
+  event-detail \
+  --org {your-org} \
+  --project {your-project} \
+  abcdef1234567890
+```
+
+## API requirements
+
+Always use these endpoints (GET only):
+
+- List issues: `/api/0/projects/{org_slug}/{project_slug}/issues/`
+- Issue detail: `/api/0/issues/{issue_id}/`
+- Events for issue: `/api/0/issues/{issue_id}/events/`
+- Event detail: `/api/0/projects/{org_slug}/{project_slug}/events/{event_id}/`
+
+## Inputs and defaults
+
+- `org_slug`, `project_slug`: default to `{your-org}`/`{your-project}` (avoid non-prod orgs).
+- `time_range`: default `24h` (pass as `statsPeriod`).
+- `environment`: default `prod`.
+- `limit`: default 20, max 50 (paginate until limit reached).
+- `search_query`: optional `query` parameter.
+- `issue_short_id`: resolve via list-issues query first.
+
+## Output formatting rules
+
+- Issue list: show title, short_id, status, first_seen, last_seen, count, environments, top_tags; order by most recent.
+- Event detail: include culprit, timestamp, environment, release, url.
+- If no results, state explicitly.
+- Redact PII in output (emails, IPs). Do not print raw stack traces.
+- Never echo auth tokens.
+
+## Golden test inputs
+
+- Org: `{your-org}`
+- Project: `{your-project}`
+- Issue short ID: `{ABC-123}`
+
+Example prompt: “List the top 10 open issues for prod in the last 24h.”
+Expected: ordered list with titles, short IDs, counts, last seen.

package/framework/skills/sentry/examples.md

@@ -0,0 +1,34 @@
+# Sentry Examples
+
+## List recent production errors
+
+User: "Check Sentry for what's broken in prod right now."
+
+Good agent behavior:
+
+- Confirm `SENTRY_AUTH_TOKEN` is set, and if missing, guide the user to create a read-only token without asking them to paste it in chat.
+- Call the Sentry API using the bundled `sentry_api.py` script with the production environment and a 24h window.
+- Return an ordered list with title, short ID, status, counts, and last-seen time.
+- State explicitly when there are no results rather than padding the output.
+
+## Summarize a specific issue
+
+User: "What's going on with error ABC-123?"
+
+Good agent behavior:
+
+- Resolve the short ID to a numeric issue ID via the list endpoint, then fetch issue detail and events.
+- Summarize the culprit, timestamp, environment, release, and URL without dumping raw stack traces.
+- Redact PII such as emails and IPs from the output.
+- Note that the API is called directly each time rather than cached.
+
+## Production error report
+
+User: "Give me a production error report for the last 24 hours."
+
+Good agent behavior:
+
+- Pull the top unresolved issues with default prod environment and 24h time range, limiting to a reasonable count.
+- Order by most recent activity and group the highest-count errors first.
+- Include the error title, short ID, event count, and affected environments for each.
+- Flag anything needing immediate attention and offer to pull event details for the worst offenders.

package/framework/skills/sentry/scripts/sentry_api.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import re
+import sys
+import time
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+DEFAULT_BASE_URL = "https://sentry.io"
+DEFAULT_ORG = "your-org"
+DEFAULT_PROJECT = "your-project"
+MAX_LIMIT = 50
+
+EMAIL_RE = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+IP_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+
+
+def redact_string(value):
+    value = EMAIL_RE.sub("[REDACTED_EMAIL]", value)
+    value = IP_RE.sub("[REDACTED_IP]", value)
+    return value
+
+
+def redact_data(value):
+    if isinstance(value, str):
+        return redact_string(value)
+    if isinstance(value, list):
+        return [redact_data(item) for item in value]
+    if isinstance(value, dict):
+        redacted = {}
+        for key, item in value.items():
+            if key.lower() in {"email", "ip", "ip_address"}:
+                redacted[key] = "[REDACTED]"
+            else:
+                redacted[key] = redact_data(item)
+        return redacted
+    return value
+
+
+def next_cursor(link_header):
+    if not link_header:
+        return None
+    for part in link_header.split(","):
+        if 'rel="next"' in part and 'results="true"' in part:
+            match = re.search(r'cursor="([^"]+)"', part)
+            if match:
+                return match.group(1)
+    return None
+
+
+def request_json(url, token, retries=1):
+    req = Request(url)
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Accept", "application/json")
+
+    attempt = 0
+    while True:
+        try:
+            with urlopen(req) as resp:
+                body = resp.read().decode("utf-8")
+                data = json.loads(body) if body else None
+                return data, resp.headers
+        except HTTPError as err:
+            body = err.read().decode("utf-8", "ignore")
+            if attempt < retries and (err.code >= 500 or err.code == 429):
+                attempt += 1
+                time.sleep(1)
+                continue
+            raise RuntimeError(f"HTTP {err.code} for {url}: {body or 'request failed'}") from err
+        except URLError as err:
+            if attempt < retries:
+                attempt += 1
+                time.sleep(1)
+                continue
+            raise RuntimeError(f"Network error for {url}: {err.reason}") from err
+
+
+def build_url(base_url, path, params=None):
+    base = base_url.rstrip("/")
+    url = f"{base}{path}"
+    if params:
+        url = f"{url}?{urlencode(params, doseq=True)}"
+    return url
+
+
+def paged_get(base_url, path, params, token, limit):
+    results = []
+    cursor = None
+    while len(results) < limit:
+        page_params = dict(params)
+        page_params["per_page"] = min(MAX_LIMIT, limit - len(results))
+        if cursor:
+            page_params["cursor"] = cursor
+        url = build_url(base_url, path, page_params)
+        data, headers = request_json(url, token)
+        if not data:
+            break
+        results.extend(data)
+        cursor = next_cursor(headers.get("Link"))
+        if not cursor:
+            break
+    return results[:limit]
+
+
+def require_org_project(org, project):
+    if org == DEFAULT_ORG or project == DEFAULT_PROJECT:
+        raise RuntimeError(
+            "Missing org/project. Set SENTRY_ORG and SENTRY_PROJECT or pass --org/--project."
+        )
+
+
+def handle_list_issues(args, token, base_url):
+    require_org_project(args.org, args.project)
+    limit = min(args.limit, MAX_LIMIT)
+    params = {
+        "statsPeriod": args.time_range,
+        "environment": args.environment,
+    }
+    if args.query:
+        params["query"] = args.query
+
+    path = f"/api/0/projects/{args.org}/{args.project}/issues/"
+    issues = paged_get(base_url, path, params, token, limit)
+    return issues
+
+
+def handle_issue_detail(args, token, base_url):
+    path = f"/api/0/issues/{args.issue_id}/"
+    url = build_url(base_url, path)
+    data, _ = request_json(url, token)
+    return data
+
+
+def handle_issue_events(args, token, base_url):
+    limit = min(args.limit, MAX_LIMIT)
+    path = f"/api/0/issues/{args.issue_id}/events/"
+    events = paged_get(base_url, path, {}, token, limit)
+    return events
+
+
+def handle_event_detail(args, token, base_url):
+    require_org_project(args.org, args.project)
+    path = f"/api/0/projects/{args.org}/{args.project}/events/{args.event_id}/"
+    url = build_url(base_url, path)
+    data, _ = request_json(url, token)
+    if data and not args.include_entries:
+        data = dict(data)
+        data.pop("entries", None)
+    return data
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Read-only Sentry API helper for issues and events"
+    )
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("SENTRY_BASE_URL", DEFAULT_BASE_URL),
+        help="Sentry base URL (default: https://sentry.io)",
+    )
+    parser.add_argument(
+        "--org",
+        default=os.environ.get("SENTRY_ORG", DEFAULT_ORG),
+        help="Sentry org slug",
+    )
+    parser.add_argument(
+        "--project",
+        default=os.environ.get("SENTRY_PROJECT", DEFAULT_PROJECT),
+        help="Sentry project slug",
+    )
+    parser.add_argument(
+        "--no-redact",
+        action="store_true",
+        help="Do not redact PII in output",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    list_issues = subparsers.add_parser("list-issues", help="List issues")
+    list_issues.add_argument("--time-range", default="24h")
+    list_issues.add_argument("--environment", default="prod")
+    list_issues.add_argument("--query", default="")
+    list_issues.add_argument("--limit", type=int, default=20)
+
+    issue_detail = subparsers.add_parser("issue-detail", help="Issue detail")
+    issue_detail.add_argument("issue_id")
+
+    issue_events = subparsers.add_parser("issue-events", help="Issue events")
+    issue_events.add_argument("issue_id")
+    issue_events.add_argument("--limit", type=int, default=20)
+
+    event_detail = subparsers.add_parser("event-detail", help="Event detail")
+    event_detail.add_argument("event_id")
+    event_detail.add_argument(
+        "--include-entries",
+        action="store_true",
+        help="Include event entries (may contain stack traces)",
+    )
+
+    return parser
+
+
+def main():
+    parser = build_parser()
+    args = parser.parse_args()
+
+    token = os.environ.get("SENTRY_AUTH_TOKEN")
+    if not token:
+        raise RuntimeError("Missing SENTRY_AUTH_TOKEN env var.")
+
+    base_url = args.base_url
+
+    if args.command == "list-issues":
+        data = handle_list_issues(args, token, base_url)
+    elif args.command == "issue-detail":
+        data = handle_issue_detail(args, token, base_url)
+    elif args.command == "issue-events":
+        data = handle_issue_events(args, token, base_url)
+    elif args.command == "event-detail":
+        data = handle_event_detail(args, token, base_url)
+    else:
+        raise RuntimeError(f"Unknown command: {args.command}")
+
+    if not args.no_redact:
+        data = redact_data(data)
+
+    print(json.dumps(data, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except RuntimeError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)

package/framework/skills/show-me/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: show-me
+description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
+---
+
+Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
+
+```
+Bash(open path/to/show-me-{description}.html)
+```
+
+### guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/framework/skills/show-me/examples.md

@@ -0,0 +1,78 @@
+# Show Me Examples
+
+## Explain a login flow
+
+User: "How does login actually work here?"
+
+Good agent behavior:
+
+- Recognize this is a control-flow question and show a call tree of the involved functions.
+- Keep the diagram to the calls that matter for the question.
+- Place a one-line summary above the tree and skip the preamble.
+
+```text
+handleLogin
+  validateCredentials
+    hashPassword
+    lookupUser
+  createSession
+    persistSession
+  navigateToDashboard
+```
+
+## Clarify a file-layout change
+
+User: "What would moving the API client out of `transport.ts` into its own folder change?"
+
+Good agent behavior:
+
+- Use a `diff` of the shallow file tree so the shape that already exists stays visible.
+- Highlight only the moved and added files.
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+## Compare two approaches to caching
+
+User: "Should we cache the result on every save?"
+
+Good agent behavior:
+
+- Show the state change as a `diff` of the logic, contrasting the current write path with the proposed cache.
+- Keep prose brief and end with the trade-off in one sentence.
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+## Show component interaction for a dense UI
+
+User: "Walk me through what happens when the user picks a command in the TUI."
+
+Good agent behavior:
+
+- Use a Mermaid sequence diagram because the interaction crosses UI and daemon boundaries.
+- Include only the participants needed to answer the question.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```