Release v1.5.0

Author: numman-ali

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-01-17
+
+### Added
+
+- **`openskills update`** - Refresh installed skills from their recorded source (default: all)
+- **Source metadata tracking** - Install now records origin info for reliable updates
+
+### Changed
+
+- **Multi-skill read** - `openskills read` supports comma-separated names
+- **Generated usage text** - Clarified read invocation for shell usage
+- **README** - Added update guidance and human usage tips
+
+### Fixed
+
+- **Update UX** - Skips skills without source metadata and lists them for re-install
+
 ## [1.3.0] - 2025-12-14
 
 ### Added
@@ -121,6 +138,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [1.3.1]: https://github.com/numman-ali/openskills/compare/v1.3.0...v1.3.1
 [1.3.2]: https://github.com/numman-ali/openskills/compare/v1.3.1...v1.3.2
 [1.4.0]: https://github.com/numman-ali/openskills/compare/v1.3.2...v1.4.0
+[1.5.0]: https://github.com/numman-ali/openskills/compare/v1.4.0...v1.5.0
 [1.2.1]: https://github.com/numman-ali/openskills/compare/v1.2.0...v1.2.1
 [1.2.0]: https://github.com/numman-ali/openskills/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/numman-ali/openskills/compare/v1.0.0...v1.1.0

README.md

@@ -97,7 +97,7 @@ So any agent that can read `AGENTS.md` can use Claude Code skills without needin
 When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively.
 
 How to use skills:
-- Invoke: Bash("npx openskills read <skill-name>")
+- Invoke: `npx openskills read <skill-name>` (run in your shell)
 - The skill content will load with detailed instructions
 - Base directory provided in output for resolving bundled resources
 
@@ -175,6 +175,7 @@ npx openskills install <source> [options]  # Install from GitHub, local path, or
 npx openskills sync [-y] [-o <path>]       # Update AGENTS.md (or custom output)
 npx openskills list                        # Show installed skills
 npx openskills read <name>                 # Load skill (for agents)
+npx openskills update [name...]            # Update installed skills (default: all)
 npx openskills manage                      # Remove skills (interactive)
 npx openskills remove <name>               # Remove specific skill
 ```
@@ -252,6 +253,31 @@ npx openskills read skill-creator
 
 ---
 
+## 🔄 Updating Skills
+
+If you installed skills from a git repo, you can refresh them anytime:
+
+```bash
+npx openskills update
+```
+
+To update specific skills, pass a comma-separated list:
+
+```bash
+npx openskills update git-workflow,check-branch-first
+```
+
+If a skill was installed before updates were tracked, re-install it once to record its source.
+
+---
+
+## ✅ Tips
+
+- You can always run OpenSkills via `npx`; a global install is optional.
+- For multiple reads, prefer comma-separated names: `npx openskills read foo,bar`.
+
+---
+
 ## ❓ FAQ
 
 ### Why CLI instead of MCP?

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "openskills",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Universal skills loader for AI coding agents - install and load Anthropic SKILL.md format skills in any agent",
   "type": "module",
   "main": "./dist/cli.js",

package.json

@@ -7,6 +7,7 @@ import { readSkill } from './commands/read.js';
 import { removeSkill } from './commands/remove.js';
 import { manageSkills } from './commands/manage.js';
 import { syncAgentsMd } from './commands/sync.js';
+import { updateSkills } from './commands/update.js';
 import { createRequire } from 'module';
 
 const program = new Command();
@@ -49,10 +50,15 @@ program
   .action(installSkill);
 
 program
-  .command('read <skill-name>')
-  .description('Read skill to stdout (for AI agents)')
+  .command('read <skill-names...>')
+  .description('Read skill(s) to stdout (for AI agents)')
   .action(readSkill);
 
+program
+  .command('update [skill-names...]')
+  .description('Update installed skills from their source (default: all)')
+  .action(updateSkills);
+
 program
   .command('sync')
   .description('Update AGENTS.md with installed skills (interactive, pre-selects current state)')

src/cli.ts

@@ -1,5 +1,5 @@
 import { readFileSync, readdirSync, existsSync, mkdirSync, rmSync, cpSync, statSync } from 'fs';
-import { join, basename, resolve, sep } from 'path';
+import { join, basename, resolve, sep, relative } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
 import chalk from 'chalk';
@@ -8,7 +8,16 @@ import { checkbox, confirm } from '@inquirer/prompts';
 import { ExitPromptError } from '@inquirer/core';
 import { hasValidFrontmatter, extractYamlField } from '../utils/yaml.js';
 import { ANTHROPIC_MARKETPLACE_SKILLS } from '../utils/marketplace-skills.js';
+import { writeSkillMetadata } from '../utils/skill-metadata.js';
 import type { InstallOptions } from '../types.js';
+import type { SkillSourceMetadata, SkillSourceType } from '../utils/skill-metadata.js';
+
+interface InstallSourceInfo {
+  source: string;
+  sourceType: SkillSourceType;
+  repoUrl?: string;
+  localRoot?: string;
+}
 
 /**
  * Check if source is a local path
@@ -101,7 +110,12 @@ export async function installSkill(source: string, options: InstallOptions): Pro
   // Handle local path installation
   if (isLocalPath(source)) {
     const localPath = expandPath(source);
-    await installFromLocal(localPath, targetDir, options);
+    const sourceInfo: InstallSourceInfo = {
+      source,
+      sourceType: 'local',
+      localRoot: localPath,
+    };
+    await installFromLocal(localPath, targetDir, options, sourceInfo);
     printPostInstallHints(isProject);
     return;
   }
@@ -131,6 +145,11 @@ export async function installSkill(source: string, options: InstallOptions): Pro
   // Clone and install from git
   const tempDir = join(homedir(), `.openskills-temp-${Date.now()}`);
   mkdirSync(tempDir, { recursive: true });
+  const sourceInfo: InstallSourceInfo = {
+    source,
+    sourceType: 'git',
+    repoUrl,
+  };
 
   try {
     const spinner = ora('Cloning repository...').start();
@@ -152,10 +171,10 @@ export async function installSkill(source: string, options: InstallOptions): Pro
     const repoDir = join(tempDir, 'repo');
 
     if (skillSubpath) {
-      await installSpecificSkill(repoDir, skillSubpath, targetDir, isProject, options);
+      await installSpecificSkill(repoDir, skillSubpath, targetDir, isProject, options, sourceInfo);
     } else {
       const repoName = getRepoName(repoUrl);
-      await installFromRepo(repoDir, targetDir, options, repoName || undefined);
+      await installFromRepo(repoDir, targetDir, options, repoName || undefined, sourceInfo);
     }
   } finally {
     rmSync(tempDir, { recursive: true, force: true });
@@ -177,7 +196,12 @@ function printPostInstallHints(isProject: boolean): void {
 /**
  * Install from local path (directory containing skills or single skill)
  */
-async function installFromLocal(localPath: string, targetDir: string, options: InstallOptions): Promise<void> {
+async function installFromLocal(
+  localPath: string,
+  targetDir: string,
+  options: InstallOptions,
+  sourceInfo: InstallSourceInfo
+): Promise<void> {
   if (!existsSync(localPath)) {
     console.error(chalk.red(`Error: Path does not exist: ${localPath}`));
     process.exit(1);
@@ -194,10 +218,10 @@ async function installFromLocal(localPath: string, targetDir: string, options: I
   if (existsSync(skillMdPath)) {
     // Single skill directory
     const isProject = targetDir.includes(process.cwd());
-    await installSingleLocalSkill(localPath, targetDir, isProject, options);
+    await installSingleLocalSkill(localPath, targetDir, isProject, options, sourceInfo);
   } else {
     // Directory containing multiple skills
-    await installFromRepo(localPath, targetDir, options);
+    await installFromRepo(localPath, targetDir, options, undefined, sourceInfo);
   }
 }
 
@@ -208,7 +232,8 @@ async function installSingleLocalSkill(
   skillDir: string,
   targetDir: string,
   isProject: boolean,
-  options: InstallOptions
+  options: InstallOptions,
+  sourceInfo: InstallSourceInfo
 ): Promise<void> {
   const skillMdPath = join(skillDir, 'SKILL.md');
   const content = readFileSync(skillMdPath, 'utf-8');
@@ -235,6 +260,7 @@ async function installSingleLocalSkill(
   }
 
   cpSync(skillDir, targetPath, { recursive: true, dereference: true });
+  writeSkillMetadata(targetPath, buildLocalMetadata(sourceInfo, skillDir));
 
   console.log(chalk.green(`✅ Installed: ${skillName}`));
   console.log(`   Location: ${targetPath}`);
@@ -248,7 +274,8 @@ async function installSpecificSkill(
   skillSubpath: string,
   targetDir: string,
   isProject: boolean,
-  options: InstallOptions
+  options: InstallOptions,
+  sourceInfo: InstallSourceInfo
 ): Promise<void> {
   const skillDir = join(repoDir, skillSubpath);
   const skillMdPath = join(skillDir, 'SKILL.md');
@@ -282,6 +309,7 @@ async function installSpecificSkill(
     process.exit(1);
   }
   cpSync(skillDir, targetPath, { recursive: true, dereference: true });
+  writeSkillMetadata(targetPath, buildGitMetadata(sourceInfo, skillSubpath));
 
   console.log(chalk.green(`✅ Installed: ${skillName}`));
   console.log(`   Location: ${targetPath}`);
@@ -294,7 +322,8 @@ async function installFromRepo(
   repoDir: string,
   targetDir: string,
   options: InstallOptions,
-  repoName?: string
+  repoName: string | undefined,
+  sourceInfo: InstallSourceInfo
 ): Promise<void> {
   const rootSkillPath = join(repoDir, 'SKILL.md');
   let skillInfos: Array<{
@@ -444,6 +473,7 @@ async function installFromRepo(
       continue;
     }
     cpSync(info.skillDir, info.targetPath, { recursive: true, dereference: true });
+    writeSkillMetadata(info.targetPath, buildMetadataFromSource(sourceInfo, info.skillDir, repoDir));
 
     console.log(chalk.green(`✅ Installed: ${info.skillName}`));
     installedCount++;
@@ -452,6 +482,38 @@ async function installFromRepo(
   console.log(chalk.green(`\n✅ Installation complete: ${installedCount} skill(s) installed`));
 }
 
+function buildMetadataFromSource(
+  sourceInfo: InstallSourceInfo,
+  skillDir: string,
+  repoDir: string
+): SkillSourceMetadata {
+  if (sourceInfo.sourceType === 'local') {
+    return buildLocalMetadata(sourceInfo, skillDir);
+  }
+  const subpath = relative(repoDir, skillDir);
+  const normalizedSubpath = subpath === '' ? '' : subpath;
+  return buildGitMetadata(sourceInfo, normalizedSubpath);
+}
+
+function buildGitMetadata(sourceInfo: InstallSourceInfo, subpath: string): SkillSourceMetadata {
+  return {
+    source: sourceInfo.source,
+    sourceType: 'git',
+    repoUrl: sourceInfo.repoUrl,
+    subpath,
+    installedAt: new Date().toISOString(),
+  };
+}
+
+function buildLocalMetadata(sourceInfo: InstallSourceInfo, skillDir: string): SkillSourceMetadata {
+  return {
+    source: sourceInfo.source,
+    sourceType: 'local',
+    localPath: skillDir,
+    installedAt: new Date().toISOString(),
+  };
+}
+
 /**
  * Warn if installing could conflict with Claude Code marketplace
  * Returns true if should proceed, false if should skip

src/commands/install.ts

@@ -1,14 +1,30 @@
 import { readFileSync } from 'fs';
 import { findSkill } from '../utils/skills.js';
+import { normalizeSkillNames } from '../utils/skill-names.js';
 
 /**
  * Read skill to stdout (for AI agents)
  */
-export function readSkill(skillName: string): void {
-  const skill = findSkill(skillName);
+export function readSkill(skillNames: string[] | string): void {
+  const names = normalizeSkillNames(skillNames);
+  if (names.length === 0) {
+    console.error('Error: No skill names provided');
+    process.exit(1);
+  }
+  const resolved = [];
+  const missing = [];
 
-  if (!skill) {
-    console.error(`Error: Skill '${skillName}' not found`);
+  for (const name of names) {
+    const skill = findSkill(name);
+    if (!skill) {
+      missing.push(name);
+      continue;
+    }
+    resolved.push({ name, skill });
+  }
+
+  if (missing.length > 0) {
+    console.error(`Error: Skill(s) not found: ${missing.join(', ')}`);
     console.error('\nSearched:');
     console.error('  .agent/skills/ (project universal)');
     console.error('  ~/.agent/skills/ (global universal)');
@@ -18,13 +34,15 @@ export function readSkill(skillName: string): void {
     process.exit(1);
   }
 
-  const content = readFileSync(skill.path, 'utf-8');
+  for (const { name, skill } of resolved) {
+    const content = readFileSync(skill.path, 'utf-8');
 
-  // Output in Claude Code format
-  console.log(`Reading: ${skillName}`);
-  console.log(`Base directory: ${skill.baseDir}`);
-  console.log('');
-  console.log(content);
-  console.log('');
-  console.log(`Skill read: ${skillName}`);
+    // Output in Claude Code format
+    console.log(`Reading: ${name}`);
+    console.log(`Base directory: ${skill.baseDir}`);
+    console.log('');
+    console.log(content);
+    console.log('');
+    console.log(`Skill read: ${name}`);
+  }
 }