pretticlaw 0.1.0

package/src/heartbeat/service.ts

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { LLMProvider } from "../providers/base.js";
+
+const HEARTBEAT_TOOL = [{
+  type: "function",
+  function: {
+    name: "heartbeat",
+    description: "Report heartbeat decision after reviewing tasks.",
+    parameters: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["skip", "run"] },
+        tasks: { type: "string" },
+      },
+      required: ["action"],
+    },
+  },
+}];
+
+export class HeartbeatService {
+  private running = false;
+  private timer: NodeJS.Timeout | null = null;
+
+  constructor(
+    private readonly workspace: string,
+    private readonly provider: LLMProvider,
+    private readonly model: string,
+    private readonly onExecute?: (tasks: string) => Promise<string>,
+    private readonly onNotify?: (response: string) => Promise<void>,
+    private readonly intervalS = 1800,
+    private readonly enabled = true,
+  ) {}
+
+  private get heartbeatFile(): string {
+    return path.join(this.workspace, "HEARTBEAT.md");
+  }
+
+  private readHeartbeat(): string | null {
+    if (!fs.existsSync(this.heartbeatFile)) return null;
+    const text = fs.readFileSync(this.heartbeatFile, "utf8");
+    return text.trim() ? text : null;
+  }
+
+  private async decide(content: string): Promise<{ action: "skip" | "run"; tasks: string }> {
+    const response = await this.provider.chat({
+      model: this.model,
+      messages: [
+        { role: "system", content: "You are a heartbeat agent. Call the heartbeat tool to report your decision." },
+        { role: "user", content: `Review the following HEARTBEAT.md and decide whether there are active tasks.\n\n${content}` },
+      ],
+      tools: HEARTBEAT_TOOL,
+    });
+    if (!response.toolCalls.length) return { action: "skip", tasks: "" };
+    const args = response.toolCalls[0].arguments;
+    const action = args.action === "run" ? "run" : "skip";
+    const tasks = typeof args.tasks === "string" ? args.tasks : "";
+    return { action, tasks };
+  }
+
+  async start(): Promise<void> {
+    if (!this.enabled || this.running) return;
+    this.running = true;
+    this.schedule();
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+  }
+
+  private schedule(): void {
+    if (!this.running) return;
+    this.timer = setTimeout(() => void this.tick().finally(() => this.schedule()), this.intervalS * 1000);
+  }
+
+  private async tick(): Promise<void> {
+    const content = this.readHeartbeat();
+    if (!content) return;
+    const { action, tasks } = await this.decide(content);
+    if (action !== "run") return;
+    if (!this.onExecute) return;
+    const response = await this.onExecute(tasks);
+    if (response && this.onNotify) await this.onNotify(response);
+  }
+
+  async triggerNow(): Promise<string | null> {
+    const content = this.readHeartbeat();
+    if (!content) return null;
+    const { action, tasks } = await this.decide(content);
+    if (action !== "run" || !this.onExecute) return null;
+    return this.onExecute(tasks);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { buildProgram } from "./cli/commands.js";
+
+const program = buildProgram();
+program.parseAsync(process.argv);

package/src/providers/base.ts

@@ -0,0 +1,43 @@
+export interface ToolCallRequest {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+export interface LLMResponse {
+  content: string | null;
+  toolCalls: ToolCallRequest[];
+  finishReason: string;
+  usage: Record<string, number>;
+  reasoningContent: string | null;
+}
+
+export interface LLMProvider {
+  chat(input: {
+    messages: Array<Record<string, unknown>>;
+    tools?: Array<Record<string, unknown>>;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+  }): Promise<LLMResponse>;
+  getDefaultModel(): string;
+}
+
+export function sanitizeEmptyContent(messages: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return messages.map((msg) => {
+    const content = msg.content;
+    if (typeof content === "string" && content.length === 0) {
+      if (msg.role === "assistant" && msg.tool_calls) return { ...msg, content: null };
+      return { ...msg, content: "(empty)" };
+    }
+    if (Array.isArray(content)) {
+      const filtered = content.filter((item) => !(typeof item === "object" && item && ["text", "input_text", "output_text"].includes((item as any).type) && !(item as any).text));
+      if (filtered.length !== content.length) {
+        if (filtered.length > 0) return { ...msg, content: filtered };
+        if (msg.role === "assistant" && msg.tool_calls) return { ...msg, content: null };
+        return { ...msg, content: "(empty)" };
+      }
+    }
+    return msg;
+  });
+}

package/src/providers/custom-provider.ts

@@ -0,0 +1,46 @@
+import OpenAI from "openai";
+import type { LLMProvider, LLMResponse, ToolCallRequest } from "./base.js";
+import { sanitizeEmptyContent } from "./base.js";
+
+export class CustomProvider implements LLMProvider {
+  private client: OpenAI;
+  constructor(private readonly apiKey: string, private readonly apiBase: string, private readonly defaultModel: string) {
+    this.client = new OpenAI({ apiKey, baseURL: apiBase });
+  }
+
+  getDefaultModel(): string {
+    return this.defaultModel;
+  }
+
+  async chat(input: { messages: Array<Record<string, unknown>>; tools?: Array<Record<string, unknown>>; model?: string; maxTokens?: number; temperature?: number; }): Promise<LLMResponse> {
+    try {
+      const res = await this.client.chat.completions.create({
+        model: input.model ?? this.defaultModel,
+        messages: sanitizeEmptyContent(input.messages) as any,
+        tools: input.tools as any,
+        tool_choice: input.tools ? "auto" : undefined,
+        max_tokens: Math.max(1, input.maxTokens ?? 4096),
+        temperature: input.temperature ?? 0.7,
+      });
+      const choice = res.choices[0];
+      const toolCalls: ToolCallRequest[] = (choice.message.tool_calls ?? []).map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: JSON.parse(tc.function.arguments || "{}"),
+      }));
+      return {
+        content: choice.message.content,
+        toolCalls,
+        finishReason: choice.finish_reason ?? "stop",
+        usage: {
+          prompt_tokens: res.usage?.prompt_tokens ?? 0,
+          completion_tokens: res.usage?.completion_tokens ?? 0,
+          total_tokens: res.usage?.total_tokens ?? 0,
+        },
+        reasoningContent: null,
+      };
+    } catch (err) {
+      return { content: `Error: ${String(err)}`, toolCalls: [], finishReason: "error", usage: {}, reasoningContent: null };
+    }
+  }
+}

package/src/providers/litellm-provider.ts

@@ -0,0 +1,131 @@
+import { nanoid } from "nanoid";
+import type { LLMProvider, LLMResponse, ToolCallRequest } from "./base.js";
+import { sanitizeEmptyContent } from "./base.js";
+
+export class LiteLLMProvider implements LLMProvider {
+  private static readonly DEFAULT_BASE_BY_PROVIDER: Record<string, string> = {
+    openrouter: "https://openrouter.ai/api/v1",
+    openai: "https://api.openai.com/v1",
+    deepseek: "https://api.deepseek.com/v1",
+    groq: "https://api.groq.com/openai/v1",
+    moonshot: "https://api.moonshot.ai/v1",
+    minimax: "https://api.minimax.io/v1",
+    dashscope: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+    zhipu: "https://open.bigmodel.cn/api/paas/v4",
+    siliconflow: "https://api.siliconflow.cn/v1",
+    volcengine: "https://ark.cn-beijing.volces.com/api/v3",
+    vllm: "http://localhost:8000/v1",
+    custom: "http://localhost:8000/v1",
+  };
+
+  private static readonly UNSUPPORTED_PROVIDERS = new Set(["anthropic", "gemini", "openai_codex", "github_copilot"]);
+
+  constructor(
+    private readonly apiKey: string | null,
+    private readonly apiBase: string | null,
+    private readonly defaultModel: string,
+    private readonly providerName: string | null,
+  ) {}
+
+  getDefaultModel(): string {
+    return this.defaultModel;
+  }
+
+  resolveModel(model: string): string {
+    const canonicalize = (s: string) => s.toLowerCase().replace(/-/g, "_");
+    if (model.includes("/")) {
+      const [prefix, rest] = model.split("/", 2);
+      if (canonicalize(prefix) === "github_copilot") return `github_copilot/${rest}`;
+      if (canonicalize(prefix) === "openai_codex") return `openai_codex/${rest}`;
+      // Groq OpenAI-compatible endpoint expects model ids like:
+      //   llama-3.3-70b-versatile
+      //   openai/gpt-oss-120b
+      // so a "groq/" prefix should be stripped.
+      if (canonicalize(prefix) === "groq") {
+        if (rest === "compound" || rest === "compound-mini") return `groq/${rest}`;
+        return rest;
+      }
+    }
+    return model;
+  }
+
+  async chat(input: { messages: Array<Record<string, unknown>>; tools?: Array<Record<string, unknown>>; model?: string; maxTokens?: number; temperature?: number; }): Promise<LLMResponse> {
+    const model = this.resolveModel(input.model ?? this.defaultModel);
+    const body: Record<string, unknown> = {
+      model,
+      messages: sanitizeEmptyContent(input.messages),
+      max_tokens: Math.max(1, input.maxTokens ?? 4096),
+      temperature: input.temperature ?? 0.7,
+    };
+    if (input.tools?.length) {
+      body.tools = input.tools;
+      body.tool_choice = "auto";
+    }
+
+    try {
+      const providerGuess = (this.providerName ?? "").trim();
+      if (providerGuess && LiteLLMProvider.UNSUPPORTED_PROVIDERS.has(providerGuess)) {
+        return {
+          content: `Error calling LLM: provider '${providerGuess}' is not supported in this TypeScript port yet. Use openrouter/openai/deepseek/groq/custom.`,
+          toolCalls: [],
+          finishReason: "error",
+          usage: {},
+          reasoningContent: null,
+        };
+      }
+
+      const apiBase =
+        this.apiBase ??
+        (providerGuess ? LiteLLMProvider.DEFAULT_BASE_BY_PROVIDER[providerGuess] : undefined) ??
+        (this.apiKey?.startsWith("sk-or-") ? LiteLLMProvider.DEFAULT_BASE_BY_PROVIDER.openrouter : undefined);
+
+      if (!apiBase) {
+        return {
+          content: "Error calling LLM: api_base not configured. Set provider/api_base in ~/.pretticlaw/config.json or run pretticlaw onboard.",
+          toolCalls: [],
+          finishReason: "error",
+          usage: {},
+          reasoningContent: null,
+        };
+      }
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (this.apiKey) headers.Authorization = `Bearer ${this.apiKey}`;
+
+      const res = await fetch(`${apiBase.replace(/\/$/, "")}/chat/completions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+      });
+      const json: any = await res.json();
+      if (!res.ok) {
+        const code = json?.error?.code ?? "";
+        const message = json?.error?.message ?? JSON.stringify(json);
+        if (code === "model_not_found") {
+          const hint = providerGuess === "groq"
+            ? "Try a Groq-supported model like llama-3.3-70b-versatile or openai/gpt-oss-120b. You can run `pretticlaw doctor`."
+            : "Check your model id and provider access. You can run `pretticlaw doctor`.";
+          return { content: `Error calling LLM: ${message}\n${hint}`, toolCalls: [], finishReason: "error", usage: {}, reasoningContent: null };
+        }
+        return { content: `Error calling LLM: ${message}`, toolCalls: [], finishReason: "error", usage: {}, reasoningContent: null };
+      }
+      const choice = json.choices?.[0]?.message ? json.choices[0] : null;
+      if (!choice) {
+        return { content: `Error calling LLM: ${JSON.stringify(json)}`, toolCalls: [], finishReason: "error", usage: {}, reasoningContent: null };
+      }
+      const toolCalls: ToolCallRequest[] = (choice.message.tool_calls ?? []).map((tc: any) => ({
+        id: nanoid(9),
+        name: tc.function.name,
+        arguments: typeof tc.function.arguments === "string" ? JSON.parse(tc.function.arguments || "{}") : tc.function.arguments,
+      }));
+      return {
+        content: choice.message.content ?? null,
+        toolCalls,
+        finishReason: choice.finish_reason ?? "stop",
+        usage: json.usage ?? {},
+        reasoningContent: choice.message.reasoning_content ?? null,
+      };
+    } catch (err) {
+      return { content: `Error calling LLM: ${String(err)}`, toolCalls: [], finishReason: "error", usage: {}, reasoningContent: null };
+    }
+  }
+}

package/src/providers/registry.ts

@@ -0,0 +1,48 @@
+import { PROVIDERS, type Config, getApiBase, getProvider, getProviderName } from "../config/schema.js";
+import type { LLMProvider } from "./base.js";
+import { CustomProvider } from "./custom-provider.js";
+import { LiteLLMProvider } from "./litellm-provider.js";
+
+export function findByModel(model: string): (typeof PROVIDERS)[number] | null {
+  const lower = model.toLowerCase();
+  const norm = lower.replace(/-/g, "_");
+  const prefix = lower.includes("/") ? lower.split("/", 1)[0].replace(/-/g, "_") : "";
+  const standard = PROVIDERS.filter((p) => !p.isGateway && !p.isLocal);
+  for (const spec of standard) {
+    if (prefix && prefix === spec.name) return spec;
+  }
+  for (const spec of standard) {
+    if (spec.keywords.some((k) => lower.includes(k) || norm.includes(k.replace(/-/g, "_")))) return spec;
+  }
+  return null;
+}
+
+export function stripModelPrefix(model: string): string {
+  if (model.startsWith("openai-codex/")) return model.slice("openai-codex/".length);
+  if (model.startsWith("openai_codex/")) return model.slice("openai_codex/".length);
+  return model;
+}
+
+export function makeProvider(config: Config): LLMProvider {
+  const model = config.agents.defaults.model;
+  const providerName = getProviderName(config, model);
+  const p = getProvider(config, model);
+
+  const oauthProviders = new Set(["openai_codex", "github_copilot"]);
+  const unsupportedInTs = new Set(["anthropic", "gemini"]);
+  if (!providerName) {
+    throw new Error("No provider could be resolved from config. Run `pretticlaw onboard` and set provider/model/API key.");
+  }
+  if (unsupportedInTs.has(providerName)) {
+    throw new Error(`Provider '${providerName}' is not supported in this TypeScript port yet. Use openrouter/openai/deepseek/groq/custom.`);
+  }
+  if (!oauthProviders.has(providerName) && providerName !== "vllm" && providerName !== "custom" && !(p?.apiKey || "").trim()) {
+    throw new Error(`No API key configured for provider '${providerName}'. Run 'pretticlaw onboard' or edit ~/.pretticlaw/config.json.`);
+  }
+
+  if (providerName === "custom") {
+    return new CustomProvider(p?.apiKey || "no-key", getApiBase(config, model) || "http://localhost:8000/v1", model);
+  }
+
+  return new LiteLLMProvider(p?.apiKey ?? null, getApiBase(config, model), model, providerName);
+}

package/src/session/manager.ts

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { nowIso } from "../types.js";
+import { ensureDir, safeFilename } from "../utils/helpers.js";
+
+export interface SessionMessage {
+  role: string;
+  content: unknown;
+  timestamp?: string;
+  tool_calls?: unknown;
+  tool_call_id?: string;
+  name?: string;
+  [k: string]: unknown;
+}
+
+export class Session {
+  key: string;
+  messages: SessionMessage[] = [];
+  createdAt: string = nowIso();
+  updatedAt: string = nowIso();
+  metadata: Record<string, unknown> = {};
+  lastConsolidated = 0;
+
+  constructor(key: string) {
+    this.key = key;
+  }
+
+  getHistory(maxMessages = 500): Array<Record<string, unknown>> {
+    const unconsolidated = this.messages.slice(this.lastConsolidated);
+    let sliced = unconsolidated.slice(-maxMessages);
+    const firstUser = sliced.findIndex((m) => m.role === "user");
+    if (firstUser > 0) sliced = sliced.slice(firstUser);
+    return sliced.map((m) => {
+      const entry: Record<string, unknown> = { role: m.role, content: m.content ?? "" };
+      for (const k of ["tool_calls", "tool_call_id", "name"]) {
+        if (k in m) entry[k] = (m as any)[k];
+      }
+      return entry;
+    });
+  }
+
+  clear(): void {
+    this.messages = [];
+    this.lastConsolidated = 0;
+    this.updatedAt = nowIso();
+  }
+}
+
+export class SessionManager {
+  private sessionsDir: string;
+  private cache = new Map<string, Session>();
+
+  constructor(workspace: string) {
+    this.sessionsDir = ensureDir(path.join(workspace, "sessions"));
+  }
+
+  private getSessionPath(key: string): string {
+    return path.join(this.sessionsDir, `${safeFilename(key.replace(":", "_"))}.jsonl`);
+  }
+
+  getOrCreate(key: string): Session {
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+    const loaded = this.load(key) ?? new Session(key);
+    this.cache.set(key, loaded);
+    return loaded;
+  }
+
+  save(session: Session): void {
+    const p = this.getSessionPath(session.key);
+    const meta = {
+      _type: "metadata",
+      key: session.key,
+      created_at: session.createdAt,
+      updated_at: session.updatedAt,
+      metadata: session.metadata,
+      last_consolidated: session.lastConsolidated,
+    };
+    const lines = [JSON.stringify(meta), ...session.messages.map((m) => JSON.stringify(m))];
+    fs.writeFileSync(p, `${lines.join("\n")}\n`, "utf8");
+    this.cache.set(session.key, session);
+  }
+
+  invalidate(key: string): void {
+    this.cache.delete(key);
+  }
+
+  listSessions(): Array<Record<string, string>> {
+    if (!fs.existsSync(this.sessionsDir)) return [];
+    const out: Array<Record<string, string>> = [];
+    for (const file of fs.readdirSync(this.sessionsDir)) {
+      if (!file.endsWith(".jsonl")) continue;
+      const p = path.join(this.sessionsDir, file);
+      try {
+        const first = fs.readFileSync(p, "utf8").split(/\r?\n/, 1)[0];
+        const meta = JSON.parse(first);
+        if (meta._type === "metadata") {
+          out.push({ key: meta.key ?? file.replace(".jsonl", ""), created_at: meta.created_at, updated_at: meta.updated_at, path: p });
+        }
+      } catch {
+        // ignore
+      }
+    }
+    return out.sort((a, b) => (b.updated_at ?? "").localeCompare(a.updated_at ?? ""));
+  }
+
+  private load(key: string): Session | null {
+    const p = this.getSessionPath(key);
+    if (!fs.existsSync(p)) return null;
+    try {
+      const lines = fs.readFileSync(p, "utf8").split(/\r?\n/).filter(Boolean);
+      const session = new Session(key);
+      for (const line of lines) {
+        const obj = JSON.parse(line);
+        if (obj._type === "metadata") {
+          session.createdAt = obj.created_at ?? session.createdAt;
+          session.updatedAt = obj.updated_at ?? session.updatedAt;
+          session.metadata = obj.metadata ?? {};
+          session.lastConsolidated = obj.last_consolidated ?? 0;
+        } else {
+          session.messages.push(obj);
+        }
+      }
+      return session;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/skills/README.md

@@ -0,0 +1,25 @@
+# Pretticlaw Skills
+
+This directory contains built-in skills that extend pretticlaw's capabilities.
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` file with:
+- YAML frontmatter (name, description, metadata)
+- Markdown instructions for the agent
+
+## Attribution
+
+These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s skill system.
+The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `github` | Interact with GitHub using the `gh` CLI |
+| `weather` | Get weather info using wttr.in and Open-Meteo |
+| `summarize` | Summarize URLs, files, and YouTube videos |
+| `tmux` | Remote-control tmux sessions |
+| `clawhub` | Search and install skills from ClawHub registry |
+| `skill-creator` | Create new skills |

package/src/skills/clawhub/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: clawhub
+description: Search and install agent skills from ClawHub, the public skill registry.
+homepage: https://clawhub.ai
+metadata: {"pretticlaw":{"emoji":"🦞"}}
+---
+
+# ClawHub
+
+Public skill registry for AI agents. Search by natural language (vector search).
+
+## When to use
+
+Use this skill when the user asks any of:
+- "find a skill for …"
+- "search for skills"
+- "install a skill"
+- "what skills are available?"
+- "update my skills"
+
+## Search
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+## Install
+
+```bash
+npx --yes clawhub@latest install <slug> --workdir ~/.pretticlaw/workspace
+```
+
+Replace `<slug>` with the skill name from search results. This places the skill into `~/.pretticlaw/workspace/skills/`, where pretticlaw loads workspace skills from. Always include `--workdir`.
+
+## Update
+
+```bash
+npx --yes clawhub@latest update --all --workdir ~/.pretticlaw/workspace
+```
+
+## List installed
+
+```bash
+npx --yes clawhub@latest list --workdir ~/.pretticlaw/workspace
+```
+
+## Notes
+
+- Requires Node.js (`npx` comes with it).
+- No API key needed for search and install.
+- Login (`npx --yes clawhub@latest login`) is only required for publishing.
+- `--workdir ~/.pretticlaw/workspace` is critical — without it, skills install to the current directory instead of the pretticlaw workspace.
+- After install, remind the user to start a new session to load the skill.

package/src/skills/cron/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: cron
+description: Schedule reminders and recurring tasks.
+---
+
+# Cron
+
+Use the `cron` tool to schedule reminders or recurring tasks.
+
+## Three Modes
+
+1. **Reminder** - message is sent directly to user
+2. **Task** - message is a task description, agent executes and sends result
+3. **One-time** - runs once at a specific time, then auto-deletes
+
+## Examples
+
+Fixed reminder:
+```
+cron(action="add", message="Time to take a break!", every_seconds=1200)
+```
+
+Dynamic task (agent executes each time):
+```
+cron(action="add", message="Check HKUDS/pretticlaw GitHub stars and report", every_seconds=600)
+```
+
+One-time scheduled task (compute ISO datetime from current time):
+```
+cron(action="add", message="Remind me about the meeting", at="<ISO datetime>")
+```
+
+Timezone-aware cron:
+```
+cron(action="add", message="Morning standup", cron_expr="0 9 * * 1-5", tz="America/Vancouver")
+```
+
+List/remove:
+```
+cron(action="list")
+cron(action="remove", job_id="abc123")
+```
+
+## Time Expressions
+
+| User says | Parameters |
+|-----------|------------|
+| every 20 minutes | every_seconds: 1200 |
+| every hour | every_seconds: 3600 |
+| every day at 8am | cron_expr: "0 8 * * *" |
+| weekdays at 5pm | cron_expr: "0 17 * * 1-5" |
+| 9am Vancouver time daily | cron_expr: "0 9 * * *", tz: "America/Vancouver" |
+| at a specific time | at: ISO datetime string (compute from current time) |
+
+## Timezone
+
+Use `tz` with `cron_expr` to schedule in a specific IANA timezone. Without `tz`, the server's local timezone is used.

package/src/skills/github/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"pretticlaw":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view <run-id> --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output.  You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```