skillfish 1.0.33 → 1.0.34

package/README.md

@@ -290,6 +290,26 @@ Your submission will be reviewed and added to [skill.fish](https://skill.fish) a
 
 ---
 
+## Private Repositories
+
+skillfish installs from private repositories when a GitHub token is available. Tokens are resolved in this order:
+
+1. `SKILLFISH_GITHUB_TOKEN` - skillfish-specific override
+2. `GITHUB_TOKEN` - standard
+3. `GH_TOKEN` - GitHub CLI standard
+4. `gh auth token` - falls back to the GitHub CLI if you're logged in
+
+The simplest setup is `gh auth login`. Otherwise, export a token before running skillfish:
+
+```bash
+export GITHUB_TOKEN=ghp_...
+skillfish add owner/private-repo
+```
+
+Public repos work with or without a token, but providing one raises the GitHub API rate limit from 60 to 5,000 requests per hour.
+
+---
+
 ## Non-Interactive Mode
 
 All commands work without prompts for use in scripts, CI pipelines, and automation. Non-interactive mode activates when:

package/dist/lib/auth.d.ts

@@ -0,0 +1,20 @@
+/**
+ * GitHub authentication helpers for skillfish.
+ */
+/**
+ * Resolve a GitHub token from the environment or the local `gh` CLI.
+ *
+ * Priority:
+ *   1. SKILLFISH_GITHUB_TOKEN
+ *   2. GITHUB_TOKEN
+ *   3. GH_TOKEN
+ *   4. `gh auth token` (if gh is on PATH and the user is logged in)
+ *
+ * Resolution happens once per process and the result is cached. Set env vars
+ * before the first call, or call `resetGitHubTokenCache()` to re-resolve.
+ */
+export declare function getGitHubToken(): string | undefined;
+/** Returns true when a GitHub token is available. */
+export declare function hasGitHubToken(): boolean;
+/** Reset the per-process token cache. Intended for use in tests only. */
+export declare function resetGitHubTokenCache(): void;

package/dist/lib/auth.js

@@ -0,0 +1,52 @@
+/**
+ * GitHub authentication helpers for skillfish.
+ */
+import { execFileSync } from 'child_process';
+// Module-scoped cache: undefined = not yet resolved, null = resolved to no token
+let cachedToken = undefined;
+/**
+ * Resolve a GitHub token from the environment or the local `gh` CLI.
+ *
+ * Priority:
+ *   1. SKILLFISH_GITHUB_TOKEN
+ *   2. GITHUB_TOKEN
+ *   3. GH_TOKEN
+ *   4. `gh auth token` (if gh is on PATH and the user is logged in)
+ *
+ * Resolution happens once per process and the result is cached. Set env vars
+ * before the first call, or call `resetGitHubTokenCache()` to re-resolve.
+ */
+export function getGitHubToken() {
+    if (cachedToken !== undefined) {
+        return cachedToken ?? undefined;
+    }
+    const fromEnv = process.env.SKILLFISH_GITHUB_TOKEN?.trim() ||
+        process.env.GITHUB_TOKEN?.trim() ||
+        process.env.GH_TOKEN?.trim();
+    if (fromEnv) {
+        cachedToken = fromEnv;
+        return cachedToken;
+    }
+    // Fallback: ask the gh CLI for the active token (~50 ms, silent on failure)
+    try {
+        const raw = execFileSync('gh', ['auth', 'token'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 2000,
+        })
+            .toString()
+            .trim();
+        cachedToken = raw || null;
+    }
+    catch {
+        cachedToken = null;
+    }
+    return cachedToken ?? undefined;
+}
+/** Returns true when a GitHub token is available. */
+export function hasGitHubToken() {
+    return getGitHubToken() !== undefined;
+}
+/** Reset the per-process token cache. Intended for use in tests only. */
+export function resetGitHubTokenCache() {
+    cachedToken = undefined;
+}

package/dist/lib/github.js

@@ -3,6 +3,7 @@
  */
 import { isGitTreeResponse, extractSkillPaths } from '../utils.js';
 import { fetchWithRetry } from './http.js';
+import { getGitHubToken, hasGitHubToken } from './auth.js';
 export const SKILL_FILENAME = 'SKILL.md';
 // === Helper Functions ===
 /**
@@ -43,7 +44,10 @@ export class RepoNotFoundError extends Error {
     owner;
     repo;
     constructor(owner, repo) {
-        super(`Repository not found: ${owner}/${repo}. Check the owner/repo name.`);
+        const hint = hasGitHubToken()
+            ? ''
+            : ', or set GITHUB_TOKEN if this is a private repository (or run `gh auth login`)';
+        super(`Repository not found: ${owner}/${repo}. Check the owner/repo name${hint}.`);
         this.owner = owner;
         this.repo = repo;
         this.name = 'RepoNotFoundError';
@@ -68,6 +72,13 @@ export class GitHubApiError extends Error {
     }
 }
 // === Helper Functions ===
+function githubHeaders() {
+    const headers = { 'User-Agent': 'skillfish' };
+    const token = getGitHubToken();
+    if (token)
+        headers['Authorization'] = `Bearer ${token}`;
+    return headers;
+}
 /**
  * Check if a response indicates rate limiting and throw RateLimitError if so.
  * @throws {RateLimitError} When rate limit is exceeded
@@ -111,7 +122,7 @@ function wrapApiError(err) {
  * @throws {NetworkError} On network errors
  */
 export async function fetchDefaultBranch(owner, repo) {
-    const headers = { 'User-Agent': 'skillfish' };
+    const headers = githubHeaders();
     const url = `https://api.github.com/repos/${owner}/${repo}`;
     try {
         const res = await fetchWithRetry(url, { headers });
@@ -137,7 +148,7 @@ export async function fetchDefaultBranch(owner, repo) {
  * Uses raw.githubusercontent.com which is not rate-limited like the API.
  */
 export async function fetchSkillMdContent(owner, repo, path, branch) {
-    const headers = { 'User-Agent': 'skillfish' };
+    const headers = githubHeaders();
     const url = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${path}`;
     try {
         const res = await fetchWithRetry(url, { headers }, 2);
@@ -159,7 +170,7 @@ export async function fetchSkillMdContent(owner, repo, path, branch) {
  * @throws {GitHubApiError} When the API response format is unexpected
  */
 export async function fetchTreeSha(owner, repo, branch) {
-    const headers = { 'User-Agent': 'skillfish' };
+    const headers = githubHeaders();
     const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}`;
     try {
         const res = await fetchWithRetry(url, { headers });
@@ -190,7 +201,7 @@ export async function fetchTreeSha(owner, repo, branch) {
  * @throws {GitHubApiError} When the API response format is unexpected
  */
 export async function fetchRecursiveTree(owner, repo, branch) {
-    const headers = { 'User-Agent': 'skillfish' };
+    const headers = githubHeaders();
     const url = `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
     try {
         const res = await fetchWithRetry(url, { headers });

package/dist/lib/installer.js

@@ -8,6 +8,7 @@ import { join } from 'path';
 import { randomUUID } from 'crypto';
 import { downloadTemplate } from 'giget';
 import { getAgentSkillDir } from './agents.js';
+import { getGitHubToken, hasGitHubToken } from './auth.js';
 import { SKILL_FILENAME } from './github.js';
 import { writeManifest, MANIFEST_VERSION, } from './manifest.js';
 /**
@@ -118,9 +119,11 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
             }
             gigetSource = `${gigetSource}#${branch}`;
         }
+        const githubToken = getGitHubToken();
         await downloadTemplate(gigetSource, {
             dir: tmpDir,
             forceClean: true,
+            ...(githubToken ? { auth: githubToken } : {}),
         });
         // Validate download
         const skillMdPath = join(tmpDir, SKILL_FILENAME);
@@ -242,7 +245,10 @@ export async function installSkill(owner, repo, skillPath, skillName, agents, op
             const errMsg = err instanceof Error ? err.message : String(err);
             // Provide more helpful error messages for common failures
             if (errMsg.includes('404') || errMsg.includes('Not Found')) {
-                result.failureReason = `Repository or path not found: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}`;
+                const hint = hasGitHubToken()
+                    ? ''
+                    : ' (set GITHUB_TOKEN if this is a private repository, or run `gh auth login`)';
+                result.failureReason = `Repository or path not found: ${owner}/${repo}${skillPath !== SKILL_FILENAME ? `/${skillPath}` : ''}${hint}`;
             }
             else {
                 result.failureReason = errMsg;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillfish",
-  "version": "1.0.33",
+  "version": "1.0.34",
   "description": "All in one Skill manager for AI coding agents. Install, update, and sync Skills across Claude Code, Cursor, Copilot + more.",
   "type": "module",
   "bin": {