What is github-gist-api?

This Claude skill streamlines the development of GitHub Gist API integrations by providing standardized, type-safe TypeScript implementation patterns. It automates the creation of Gists, ensures robust response validation using Zod, and includes specialized utilities like GistHack URL conversion for instant web hosting of Gist content, following modern best practices with the ky HTTP client.

When should I use github-gist-api?

github-gist-api is useful in the following scenarios: • Case 1: Rapidly implementing Gist creation features in TypeScript applications with built-in schema validation. • Case 2: Developing Chrome extensions that need to save, share, or sync user data and snippets via GitHub Gist. • Case 3: Converting raw Gist files into executable web content using GistHack URL transformation for previewing HTML/CSS/JS. • Case 4: Standardizing API error handling and request patterns across developer tools using ky and Zod.

name	github-gist-api
description	GitHub Gist API を使用したコードを書く際に使用。Gist作成、GistHack URL変換、ky/zod を使った実装パターンを提供。

GitHub Gist API コード生成スキル

GitHub Gist API を使用したコードを書く際は、以下の仕様に従ってください。

API 仕様

まず docs/api-github-gist.md を読んで、最新の API 仕様を確認してください。

基本ルール

HTTP クライアント: ky を使用する
レスポンス検証: zod でバリデーションする
ID生成: nanoid を使用する（必要な場合）
型安全: TypeScript で記述する

実装パターン

Gist 作成の実装

import ky from "ky";
import { z } from "zod";

// zod スキーマ
const GistFileSchema = z.object({
  filename: z.string(),
  type: z.string(),
  language: z.string().nullable(),
  raw_url: z.string().url(),
  size: z.number(),
  truncated: z.boolean(),
  content: z.string().optional(),
});

const GistResponseSchema = z.object({
  id: z.string(),
  url: z.string().url(),
  html_url: z.string().url(),
  files: z.record(z.string(), GistFileSchema),
  public: z.boolean(),
  created_at: z.string(),
  updated_at: z.string(),
  description: z.string().nullable(),
});

type GistResponse = z.infer<typeof GistResponseSchema>;

// Gist 作成
async function createGist(
  token: string,
  html: string,
  description = "Deployed via PasteHost"
): Promise<GistResponse> {
  const response = await ky
    .post("https://api.github.com/gists", {
      headers: {
        Authorization: `token ${token}`,
        Accept: "application/vnd.github.v3+json",
      },
      json: {
        description,
        public: true, // GistHack を使うため public 必須
        files: {
          "index.html": {
            content: html,
          },
        },
      },
    })
    .json();

  return GistResponseSchema.parse(response);
}

GistHack URL 変換

function convertToGistHackUrl(rawUrl: string): string {
  return rawUrl.replace(
    "gist.githubusercontent.com",
    "gist.githack.com"
  );
}

// 使用例
async function deployToGist(token: string, html: string): Promise<string> {
  const gist = await createGist(token, html);
  const rawUrl = gist.files["index.html"].raw_url;
  return convertToGistHackUrl(rawUrl);
}

エラーハンドリング

import { HTTPError } from "ky";

try {
  const url = await deployToGist(token, html);
  console.log("Deployed:", url);
} catch (error) {
  if (error instanceof HTTPError) {
    const body = await error.response.json();
    if (error.response.status === 401) {
      console.error("Authentication failed. Check your token.");
    } else if (error.response.status === 422) {
      console.error("Validation error:", body.errors);
    } else {
      console.error("GitHub API Error:", body.message);
    }
  } else if (error instanceof z.ZodError) {
    console.error("Response validation error:", error.errors);
  } else {
    throw error;
  }
}

Chrome 拡張での使用

Chrome 拡張のコンテキストでは:

chrome.storage.sync からトークンを取得
navigator.clipboard.readText() でクリップボード取得
GistHack URL を navigator.clipboard.writeText() でコピー

注意事項

ファイル名に gistfile + 数字は使用禁止（Gist内部命名と競合）
GistHack を使用するには public: true が必須
raw_url は毎回コミットハッシュが変わる

チェックリスト

コードを書く際は以下を確認:

ky を使用している（fetch直接使用は避ける）
zod でレスポンスをバリデーションしている
GistHack URL変換を実装している
public: true を設定している
エラーハンドリングが適切
型定義が正確

github-gist-api

When & Why to Use This Skill

Use Cases