antikit 1.10.1 → 1.12.0

package/README.md

@@ -10,184 +10,191 @@ npm install -g antikit
 
 ## Features
 
-- **Multi-source Support**: Fetch skills from any GitHub repository.
-- **Sub-directory Support**: Skills can reside in sub-folders (e.g. `.claude/skills`).
-- **Interactive UI**: Browse, select, and update skills with a rich terminal UI.
-- **Dependency Management**: Automatically resolves and installs skill dependencies defined in `SKILL.md`.
-- **Smart Upgrades**: Detects version changes and allows easy upgrades.
-- **Autocomplete**: Full Zsh/Bash comparison support.
+- **Multi-source Support**: Fetch skills from any GitHub repository (Public or Private).
+- **Sub-directory Support**: Skills can reside in sub-folders (e.g. `.claude/skills`) within a repo.
+- **Interactive UI**: Browse, select, multi-install, and update skills with a rich terminal interface.
+- **Private Repo Access**: Seamless integration with private repositories via GitHub Token.
+- **Smart Upgrades**: Detects version changes, manages dependencies, and streamlines updates.
+- **Autocomplete**: Full Zsh/Bash/Fish tab-completion support.
+- **Performance**: Optimized fetching using GitHub GraphQL API.
 
-## Usage
+---
+
+## 🚀 Quick Start
 
-### � Quick Start
+### 1. Setup Autocomplete (Recommended)
 
-**1. Setup Autocomplete (Recommended)**
+This enables tab completion for commands and skill names.
 
 ```bash
 antikit completion
-# Follow instructions to add to ~/.zshrc or ~/.bashrc
+# Follow the instructions to add the script to your ~/.zshrc or ~/.bashrc
 ```
 
-**2. Browse & Install Skills**
+### 2. Configure Authentication (Optional but Recommended)
 
-```bash
-antikit list
-# or simply
-antikit ls
-```
+To avoid API rate limits (60 requests/hr) and access **Private Repositories**, configure a GitHub Token.
 
-_Shows an interactive menu to search, select, and install/update skills._
+1.  **Create Token:** [Generate New Token](https://github.com/settings/tokens/new?description=antikit-cli&scopes=repo)
+    - Select scope `public_repo` (for public access) or `repo` (for private access).
+2.  **Set Token:**
+    ```bash
+    antikit config set-token ghp_YOUR_TOKEN_HERE
+    ```
 
 ---
 
-### �📦 Manage Skills
+## 📚 Usage Guide
+
+### 🔍 Discovery & Listing
 
-#### List available skills
+**Interactive Mode (Default)**
+Browse skills, see installed status, updates available, and descriptions. Use Space to select multiple skills and Enter to install.
 
 ```bash
-# Interactive mode (Default) - Browse, Multi-select, Update
-antikit ls
+antikit list
+# Alias: antikit ls
+```
 
-# Search skills by name
-antikit ls -s <query>
+**Search & Filters**
 
-# Text mode (Non-interactive list)
-antikit ls --text
+```bash
+# Search by skill name
+antikit ls -s <keyword>
 
 # Filter by source
 antikit ls --source official
+antikit ls --source claudekit
+
+# Text Mode (Non-interactive, good for scripting)
+antikit ls --text
 ```
 
-#### Install a skill
+### ⬇️ Installation & Updates
 
-Automatically installs dependencies defined in `SKILL.md`.
+**Install Skills**
+Automatically resolves and installs dependencies defined in `SKILL.md`.
 
 ```bash
 antikit install <skill-name>
-# or
-antikit i <skill-name>
+# Alias: antikit i <skill-name>
 
-# Force overwrite if exists
+# Force re-install
 antikit install <skill-name> --force
 ```
 
-#### Upgrade installed skills
-
-Update your local skills to the latest version from their sources.
+**Upgrade Skills**
+Keep your skills up-to-date with one command.
 
 ```bash
-# Upgrade all installed skills
+# Upgrade all installed skills (Interactive confirmation)
 antikit upgrade
-# or
-antikit ug
+# Alias: antikit ug
 
 # Upgrade a specific skill
 antikit upgrade <skill-name>
 
-# Upgrade without confirmation (good for scripts)
+# Upgrade all without confirmation (CI/Script mode)
 antikit upgrade --yes
 ```
 
-#### List installed local skills
+**Manage Local Skills**
 
 ```bash
+# List locally installed skills
 antikit local
-# or
-antikit l
-```
+# Alias: antikit l
 
-#### Remove a skill
-
-```bash
+# Remove a skill
 antikit remove <skill-name>
-# or
-antikit rm <skill-name>
+# Alias: antikit rm <skill-name>
 ```
 
----
+### 📡 Source Management
 
-### 📡 Manage Sources
+You can fetch skills from multiple repositories, including monorepos with sub-directories.
 
-You can fetch skills from multiple GitHub repositories, even from sub-directories.
+**List Sources**
 
 ```bash
-# List configured sources
 antikit source list
+```
+
+**Add Sources**
 
-# Add a standard Repo source (GitHub owner/repo)
-antikit source add vunamhung/antiskills
+```bash
+# Add a Public/Private GitHub Repo
+antikit source add owner/repo-name
 
-# Add a source from a SUB-DIRECTORY (e.g. monorepo)
+# Add from a specific Sub-directory (e.g. monorepo)
 antikit source add mrgoonie/claudekit-skills --path .claude/skills --name claudekit
 
-# Add with a custom name
-antikit source add vunamhung/private-skills --name private
+# Add with a custom alias
+antikit source add my-org/private-skills --name work
+```
+
+**Manage Sources**
 
-# Set a default source
-antikit source default private
+```bash
+# Set a default source for basic installs
+antikit source default work
 
 # Remove a source
-antikit source remove private
+antikit source remove work
 ```
 
----
+### ⚙️ Configuration
+
+Manage your local configuration and credentials.
 
-### 🔄 Self Update
+```bash
+# View current config (masked token)
+antikit config list
 
-Update the `antikit` CLI tool itself to the latest version.
+# Update GitHub Token
+antikit config set-token <new_token>
+
+# Remove Token
+antikit config remove-token
+```
+
+### 🔄 Tool Maintenance
+
+**Update CLI**
+Update `antikit` itself to the latest version.
 
 ```bash
 antikit update
+# Alias: antikit up
 ```
 
-_Note: You will also be notified automatically if a new version is available when running any command._
-
 ---
 
-## Skill Development
+## 🛠 Skill Development
 
 ### Skill Structure
 
-A skill is a directory containing a `SKILL.md` file.
+A skill is simply a directory containing a `SKILL.md` (metadata & instructions) and any associated files.
 
 ### Defining Version & Dependencies
 
-You can specify version and dependencies in the `SKILL.md` frontmatter.
+Add YAML frontmatter to your `SKILL.md` to enable versioning and automatic dependency installation.
 
 ```yaml
 ---
-name: my-skill
-description: A powerful skill that needs helpers
-version: 1.0.1
+name: my-complex-skill
+description: Performs magic operations
+version: 1.2.0
 dependencies:
-  - sql-helper
-  - python-runner
+  - simple-helper-skill
+  - another-dependency
 ---
-# My Skill Content
+# Skill Instructions
 ...
 ```
 
 ---
 
-### 🔐 Authentication (Optional)
-
-To increase GitHub API rate limits (avoiding "API rate limit exceeded" errors), you can configure a Personal Access Token.
-
-```bash
-# Set token
-antikit config set-token ghp_xxxxxxxxxxxx
-
-# Check config
-antikit config list
-# or
-antikit config ls
-
-# Remove token
-antikit config remove-token
-```
-
----
-
 ## Requirements
 
 - Node.js >= 18.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antikit",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "CLI tool to manage AI agent skills from Anti Gravity skills repository",
   "type": "module",
   "main": "src/index.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "semantic-release": "semantic-release",
+    "release": "commit-and-tag-version",
     "prepare": "husky",
     "format": "prettier --write ."
   },
@@ -47,16 +47,18 @@
     "@inquirer/prompts": "^8.2.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
     "omelette": "^0.4.17",
     "ora": "^8.1.1",
     "simple-git": "^3.27.0"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
+    "commit-and-tag-version": "^12.6.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
-    "prettier": "^3.7.4",
-    "semantic-release": "^24.2.0"
+    "prettier": "^3.7.4"
   }
 }

package/src/commands/info.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { marked } from 'marked';
+import TerminalRenderer from 'marked-terminal';
+import { getSkillsDir, skillExists } from '../utils/local.js';
+import { fetchSkillInfo } from '../utils/github.js';
+
+// Setup marked to render to terminal
+marked.setOptions({
+  renderer: new TerminalRenderer()
+});
+
+export async function showSkillInfo(skillName, options) {
+  if (!skillName) {
+    console.error(chalk.red('Please provide a skill name.'));
+    process.exit(1);
+  }
+
+  const skillsDir = getSkillsDir();
+  const localSkillPath = path.join(skillsDir, skillName, 'SKILL.md');
+
+  // 1. Try Local First
+  if (skillExists(skillName) && fs.existsSync(localSkillPath)) {
+    console.log(chalk.bold.green(`\n📖 Viewing local docs for: ${skillName}\n`));
+    const content = fs.readFileSync(localSkillPath, 'utf8');
+    console.log(marked(content));
+    return;
+  }
+
+  // 2. Try Remote if not found locally
+  console.log(chalk.yellow(`Skill "${skillName}" not found locally. Searching remote...`));
+  const info = await fetchSkillInfo(skillName);
+
+  if (info && info.content) {
+    // Note: fetchSkillInfo currently returns parsed metadata (desc, version).
+    // I need to update fetchSkillInfo or create a new internal function to get THE RAW CONTENT for rendering.
+    // Wait, fetchSkillInfo in github.js calculates metadata from content but currently DOES NOT return the full content string.
+    // I should update fetchSkillInfo to return 'raw' content as well.
+
+    // Let's rely on the updated logic I'm about to add to github.js to return 'content'
+    console.log(chalk.bold.blue(`\n📖 Viewing remote docs for: ${skillName}\n`));
+    console.log(marked(info.content));
+  } else {
+    // Fallback if I haven't updated github.js yet or skill not found
+    console.error(chalk.red(`\n❌ Skill "${skillName}" not found in any configured source.`));
+  }
+}

package/src/commands/list.js

@@ -111,7 +111,14 @@ function displaySkillsList(skills) {
     return acc;
   }, {});
 
-  for (const [sourceName, sourceSkills] of Object.entries(bySource)) {
+  const sortedSourceNames = Object.keys(bySource).sort((a, b) => {
+    if (a === 'official') return -1;
+    if (b === 'official') return 1;
+    return a.localeCompare(b);
+  });
+
+  for (const sourceName of sortedSourceNames) {
+    const sourceSkills = bySource[sourceName];
     console.log(chalk.magenta.bold(`\n📦 ${sourceName}`));
     for (const skill of sourceSkills) {
       let status = chalk.dim('  ');
@@ -133,8 +140,10 @@ function displaySkillsList(skills) {
 }
 
 async function interactiveInstall(skills) {
-  // Sort skills by Source then Name
+  // Sort skills by Source (Official first) then Name
   skills.sort((a, b) => {
+    if (a.source === 'official' && b.source !== 'official') return -1;
+    if (b.source === 'official' && a.source !== 'official') return 1;
     if (a.source !== b.source) return a.source.localeCompare(b.source);
     return a.name.localeCompare(b.name);
   });

package/src/commands/validate.js

@@ -0,0 +1,67 @@
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+export async function validateSkill(targetPath = '.') {
+  const absolutePath = path.resolve(targetPath);
+
+  // If targetPath is a file (SKILL.md), use it. Iterate up if needed
+  let skillMdPath = absolutePath;
+  if (!skillMdPath.endsWith('SKILL.md')) {
+    skillMdPath = path.join(absolutePath, 'SKILL.md');
+  }
+
+  console.log(chalk.bold(`Inspecting: ${skillMdPath}\n`));
+
+  if (!fs.existsSync(skillMdPath)) {
+    console.error(chalk.red('❌ SKILL.md not found!'));
+    console.log(
+      chalk.dim('Make sure you are in the root directory of the skill or provide a path.')
+    );
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf8');
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+  if (!match) {
+    console.error(chalk.red('❌ Missing or invalid YAML Frontmatter.'));
+    console.log('File must start with:\n---\nkey: value\n---');
+    process.exit(1);
+  }
+
+  const frontmatter = match[1];
+
+  // Simple parser
+  const parse = key => {
+    const m = frontmatter.match(new RegExp(`${key}:\\s*(.+)`));
+    return m ? m[1].trim() : null;
+  };
+
+  const errors = [];
+  const name = parse('name');
+  const desc = parse('description');
+  const version = parse('version');
+
+  if (!name) errors.push('Missing "name" field');
+  if (!desc) errors.push('Missing "description" field');
+  if (!version) errors.push('Missing "version" field');
+
+  if (errors.length > 0) {
+    console.error(chalk.red('❌ Validation Failed:'));
+    errors.forEach(e => console.error(chalk.red(`  - ${e}`)));
+    process.exit(1);
+  }
+
+  // Validate dependencies format if exists
+  if (frontmatter.includes('dependencies:')) {
+    // Check indentation vaguely
+    // const deps = frontmatter.match(/dependencies:\s*\n(\s+-\s+.+\n)+/);
+    // Regex validation for list is hard, let's skip deep validation for now.
+  }
+
+  console.log(chalk.green('✅ Skill Metadata is Valid!'));
+  console.log(chalk.dim('Name:       ') + chalk.cyan(name));
+  console.log(chalk.dim('Version:    ') + chalk.cyan(version));
+  console.log(chalk.dim('Description:') + desc);
+}

package/src/index.js

@@ -7,6 +7,8 @@ import { listRemoteSkills } from './commands/list.js';
 import { listLocalSkills } from './commands/local.js';
 import { installSkill } from './commands/install.js';
 import { removeSkill } from './commands/remove.js';
+import { showSkillInfo } from './commands/info.js';
+import { validateSkill } from './commands/validate.js';
 import { updateCli } from './commands/update.js';
 import { upgradeSkills } from './commands/upgrade.js';
 import { listSources, addNewSource, removeExistingSource, setDefault } from './commands/source.js';
@@ -59,6 +61,17 @@ program
   .description('Remove an installed skill')
   .action(removeSkill);
 
+program
+  .command('info <skill>')
+  .alias('doc')
+  .description('Show skill documentation (SKILL.md)')
+  .action(showSkillInfo);
+
+program
+  .command('validate [path]')
+  .description('Validate SKILL.md structure and metadata')
+  .action(validateSkill);
+
 program
   .command('update')
   .alias('up')

package/src/utils/github.js

@@ -1,7 +1,11 @@
+import chalk from 'chalk';
 import { getSources, getToken } from './configManager.js';
 
 const GITHUB_API = 'https://api.github.com';
 
+// Global flag to prevent duplicate rate limit logs
+let hasLoggedRateLimit = false;
+
 function getHeaders() {
   const headers = {
     Accept: 'application/vnd.github.v3+json',
@@ -14,6 +18,22 @@ function getHeaders() {
   return headers;
 }
 
+function logRateLimitError() {
+  if (hasLoggedRateLimit) return;
+  hasLoggedRateLimit = true;
+
+  console.error(chalk.yellow('\n⚠️  GitHub API rate limit exceeded.'));
+  console.error(
+    chalk.dim('You are seeing this because unauthenticated requests are limited to 60/hr.')
+  );
+  console.error('\nTo fix this:');
+  console.error(
+    `1. Create a token: ${chalk.underline('https://github.com/settings/tokens/new?description=antikit-cli&scopes=repo')}`
+  );
+  console.error(`2. Run command:  ${chalk.cyan('antikit config set-token <your_token>')}`);
+  console.error();
+}
+
 /**
  * Fetch skills using GraphQL (Optimized: 1 request per source)
  */
@@ -44,8 +64,7 @@ async function fetchSkillsViaGraphQL(source, token) {
     }
     `;
 
-  const branch = source.branch || 'main'; // This logic might need verifying branch exists, but usually main/master
-  // Correct expression for path. If path is provided, it's "branch:path", else just "branch:"
+  const branch = source.branch || 'main';
   const expression = source.path ? `${branch}:${source.path}` : `${branch}:`;
 
   try {
@@ -79,7 +98,6 @@ async function fetchSkillsViaGraphQL(source, token) {
         let description = null;
         let version = '0.0.0';
 
-        // Attempt to parse SKILL.md content if it exists
         const skillFile = item.object.file && item.object.file[0];
         if (skillFile && skillFile.object && skillFile.object.text) {
           const content = skillFile.object.text;
@@ -100,9 +118,10 @@ async function fetchSkillsViaGraphQL(source, token) {
           source: source.name,
           owner: source.owner,
           repo: source.repo,
+          branch: source.branch || 'main',
           basePath: source.path,
-          description, // Pre-fetched!
-          version // Pre-fetched!
+          description,
+          version
         };
       });
   } catch (e) {
@@ -114,7 +133,7 @@ async function fetchSkillsViaGraphQL(source, token) {
  * Fetch list of skills from a specific source
  */
 async function fetchSkillsFromSource(source) {
-  // Try GraphQL first if token exists (Much faster)
+  // Try GraphQL first if token exists
   const token = getToken() || process.env.ANTIKIT_GITHUB_TOKEN || process.env.GITHUB_TOKEN;
   if (token) {
     const gqlResult = await fetchSkillsViaGraphQL(source, token);
@@ -126,7 +145,6 @@ async function fetchSkillsFromSource(source) {
   if (source.path) {
     url += `/${source.path}`;
   }
-  // ... rest of function
 
   const response = await fetch(url, {
     headers: getHeaders()
@@ -137,11 +155,9 @@ async function fetchSkillsFromSource(source) {
 
     // Check for rate limit
     if (response.status === 403 && data.message.includes('rate limit')) {
-      console.error('\n⚠️  GitHub API rate limit exceeded.');
-      console.error(
-        'Please set GITHUB_TOKEN or ANTIKIT_GITHUB_TOKEN environment variable to increase limit.\n'
-      );
+      logRateLimitError();
     }
+
     // Handle empty repository
     if (data.message === 'This repository is empty.') {
       return [];
@@ -153,7 +169,7 @@ async function fetchSkillsFromSource(source) {
   const contents = await response.json();
 
   if (!Array.isArray(contents)) {
-    return []; // Handle case where path points to file, not dir
+    return [];
   }
 
   // Filter only directories (skills)
@@ -162,24 +178,39 @@ async function fetchSkillsFromSource(source) {
     .map(item => ({
       name: item.name,
       url: item.html_url,
-      path: item.path, // Full path in repo (e.g. .claude/skills/foo)
+      path: item.path,
       source: source.name,
       owner: source.owner,
       repo: source.repo,
       branch: source.branch || 'main',
-      basePath: source.path // Keep track of base path
+      basePath: source.path
     }));
 
   return skills;
 }
 
-// ... (fetchRemoteSkills remains same)
+/**
+ * Fetch list of skills from all configured sources
+ */
+export async function fetchRemoteSkills(sourceName = null) {
+  const sources = getSources();
+  const targetSources = sourceName ? sources.filter(s => s.name === sourceName) : sources;
+
+  if (targetSources.length === 0) {
+    throw new Error(`Source "${sourceName}" not found.`);
+  }
+
+  // Reset rate limit flag before new fetch
+  hasLoggedRateLimit = false;
+
+  const results = await Promise.all(targetSources.map(source => fetchSkillsFromSource(source)));
+  return results.flat();
+}
 
 /**
  * Fetch SKILL.md content for a specific skill
  */
 export async function fetchSkillInfo(skillName, owner, repo, path = null, branch = null) {
-  // If owner/repo not provided, search in all sources
   if (!owner || !repo) {
     const skills = await fetchRemoteSkills();
     const skill = skills.find(s => s.name === skillName);
@@ -192,23 +223,23 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
 
   let content = null;
 
-  // Optimized: Use Raw URL if branch is known (avoids API rate limit)
+  // Optimized: Use Raw URL if branch is known
   if (branch) {
     let rawUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}`;
     if (path) rawUrl += `/${path}`;
     rawUrl += `/${skillName}/SKILL.md`;
 
     try {
-      const res = await fetch(rawUrl);
+      const res = await fetch(rawUrl, {
+        headers: getHeaders()
+      });
       if (res.ok) {
         content = await res.text();
       }
-    } catch (e) {
-      // Ignore fetch error, fallback to API
-    }
+    } catch (e) {}
   }
 
-  // Fallback: Use API (Counts against rate limit, but works if branch is wrong/private repo needs Auth)
+  // Fallback: Use API
   if (!content) {
     let url = `${GITHUB_API}/repos/${owner}/${repo}/contents`;
     if (path) {
@@ -221,6 +252,15 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
     });
 
     if (!response.ok) {
+      // Check for rate limit also here
+      if (response.status === 403) {
+        // We can check body/headers but usually 403 here means rate limit if 404 is handled
+        // But simpler just to ignore or log if we strictly check msg
+        try {
+          const d = await response.json();
+          if (d.message.includes('rate limit')) logRateLimitError();
+        } catch {}
+      }
       return null;
     }
 
@@ -228,7 +268,6 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
     content = Buffer.from(data.content, 'base64').toString('utf-8');
   }
 
-  // Extract info from YAML frontmatter
   const match = content.match(/^---\n([\s\S]*?)\n---/);
   if (match) {
     const frontmatter = match[1];
@@ -237,11 +276,12 @@ export async function fetchSkillInfo(skillName, owner, repo, path = null, branch
 
     return {
       description: descMatch ? descMatch[1].trim() : null,
-      version: versionMatch ? versionMatch[1].trim() : '0.0.0'
+      version: versionMatch ? versionMatch[1].trim() : '0.0.0',
+      content // Return raw content
     };
   }
 
-  return { description: null, version: '0.0.0' };
+  return { description: null, version: '0.0.0', content };
 }
 
 /**