prjct-cli 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.40.0] - 2026-01-28
+
+### Feature: Enhanced Skill System
+
+Inspired by vercel-labs/skills, prjct-cli now supports remote skill installation, version tracking via lock file, and full ecosystem-standard SKILL.md subdirectory format across all skill directories.
+
+**New: Remote Skill Installation (`p. skill add`)**
+- Install skills from GitHub repos: `p. skill add owner/repo`
+- Install specific skill: `p. skill add owner/repo@skill-name`
+- Install from local directory: `p. skill add ./path`
+- Automatic source metadata injection (`_prjct` frontmatter block)
+
+**New: Skill Lock File**
+- Tracks installed skills at `~/.prjct-cli/skills/.skill-lock.json`
+- Records source URL, commit SHA, install timestamp
+- Enables update detection via `p. skill check`
+
+**New: Additional Subcommands**
+- `p. skill add <source>` — Install from GitHub or local path
+- `p. skill remove <name>` — Uninstall a skill
+- `p. skill init <name>` — Scaffold a new skill template
+- `p. skill check` — Detect available updates
+
+**Improved: Full SKILL.md Subdirectory Support**
+- All skill directories now support both `{name}.md` (flat) and `{name}/SKILL.md` (subdirectory) formats
+- Previously only provider dirs (`~/.claude/skills/`) checked subdirectories
+- Orchestrator executor now checks both patterns when loading agent skills
+
+**New Files:**
+- `core/services/skill-installer.ts` — Remote installation service
+- `core/services/skill-lock.ts` — Lock file management
+
+**Modified:**
+- `core/types/services.ts` — Extended `SkillMetadata` with `sourceUrl`, `sourceType`, `installedAt`, `sha`; added `'remote'` source type
+- `core/services/skill-service.ts` — Unified SKILL.md discovery in all dirs
+- `core/agentic/orchestrator-executor.ts` — Both path patterns for skill loading
+- `templates/commands/skill.md` — New subcommands documentation
+
 ## [0.39.0] - 2026-01-24
 
 ### Feature: Windsurf IDE Support (PRJ-66)

package/core/agentic/orchestrator-executor.ts

@@ -344,18 +344,35 @@ export class OrchestratorExecutor {
         // Skip if already loaded
         if (loadedSkillNames.has(skillName)) continue
 
-        const skillPath = path.join(skillsDir, `${skillName}.md`)
+        // Check both patterns: flat file and subdirectory (ecosystem standard)
+        const flatPath = path.join(skillsDir, `${skillName}.md`)
+        const subdirPath = path.join(skillsDir, skillName, 'SKILL.md')
+
+        let content: string | null = null
+        let resolvedPath = flatPath
+
+        // Prefer subdirectory format (ecosystem standard)
         try {
-          const content = await fs.readFile(skillPath, 'utf-8')
+          content = await fs.readFile(subdirPath, 'utf-8')
+          resolvedPath = subdirPath
+        } catch {
+          // Fall back to flat file
+          try {
+            content = await fs.readFile(flatPath, 'utf-8')
+            resolvedPath = flatPath
+          } catch {
+            // Skill not found - not an error, just skip
+            console.warn(`Skill not found: ${skillName}`)
+          }
+        }
+
+        if (content) {
           skills.push({
             name: skillName,
             content,
-            filePath: skillPath,
+            filePath: resolvedPath,
           })
           loadedSkillNames.add(skillName)
-        } catch {
-          // Skill not found - not an error, just skip
-          console.warn(`Skill not found: ${skillName}`)
         }
       }
     }

package/core/services/skill-installer.ts

@@ -0,0 +1,431 @@
+/**
+ * Skill Installer Service
+ *
+ * Installs skills from remote sources (GitHub repos, local paths).
+ * Follows the ecosystem standard of {name}/SKILL.md subdirectory format.
+ *
+ * Supported sources:
+ * - owner/repo — clone from GitHub, discover all SKILL.md files
+ * - owner/repo@skill-name — install specific skill from repo
+ * - ./local-path — install from local directory
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import { promisify } from 'util'
+import { exec as execCallback } from 'child_process'
+import { glob } from 'glob'
+
+import { skillLock } from './skill-lock'
+import type { SkillLockEntry } from './skill-lock'
+
+const exec = promisify(execCallback)
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ParsedSource {
+  type: 'github' | 'local'
+  owner?: string
+  repo?: string
+  skillName?: string
+  localPath?: string
+  url: string
+}
+
+export interface InstalledSkill {
+  name: string
+  filePath: string
+  source: ParsedSource
+  sha?: string
+}
+
+export interface InstallResult {
+  installed: InstalledSkill[]
+  skipped: string[]
+  errors: string[]
+}
+
+// =============================================================================
+// Source Parsing
+// =============================================================================
+
+/**
+ * Parse a source string into a structured source object
+ *
+ * Formats:
+ * - "owner/repo" → GitHub repo, install all skills
+ * - "owner/repo@skill-name" → GitHub repo, specific skill
+ * - "./path" or "/path" → Local directory
+ */
+export function parseSource(source: string): ParsedSource {
+  // Local path
+  if (source.startsWith('./') || source.startsWith('/') || source.startsWith('~')) {
+    const resolvedPath = source.startsWith('~')
+      ? path.join(os.homedir(), source.slice(1))
+      : path.resolve(source)
+    return {
+      type: 'local',
+      localPath: resolvedPath,
+      url: resolvedPath,
+    }
+  }
+
+  // GitHub: owner/repo@skill-name
+  const atIndex = source.indexOf('@')
+  if (atIndex > 0) {
+    const repoPath = source.slice(0, atIndex)
+    const skillName = source.slice(atIndex + 1)
+    const [owner, repo] = repoPath.split('/')
+    if (owner && repo) {
+      return {
+        type: 'github',
+        owner,
+        repo,
+        skillName,
+        url: `https://github.com/${owner}/${repo}`,
+      }
+    }
+  }
+
+  // GitHub: owner/repo
+  const parts = source.split('/')
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return {
+      type: 'github',
+      owner: parts[0],
+      repo: parts[1],
+      url: `https://github.com/${parts[0]}/${parts[1]}`,
+    }
+  }
+
+  throw new Error(`Invalid source format: "${source}". Expected "owner/repo", "owner/repo@skill-name", or "./local-path"`)
+}
+
+// =============================================================================
+// Skill Discovery
+// =============================================================================
+
+/**
+ * Discover skills in a directory by scanning for SKILL.md files
+ */
+async function discoverSkills(dir: string): Promise<Array<{ name: string; filePath: string }>> {
+  const skills: Array<{ name: string; filePath: string }> = []
+
+  // Pattern 1: {dir}/SKILL.md (root-level skill)
+  try {
+    const rootSkill = path.join(dir, 'SKILL.md')
+    await fs.access(rootSkill)
+    const dirName = path.basename(dir)
+    skills.push({ name: dirName, filePath: rootSkill })
+  } catch {
+    // No root SKILL.md
+  }
+
+  // Pattern 2: {dir}/*/SKILL.md (subdirectory skills)
+  const subdirSkills = await glob('*/SKILL.md', { cwd: dir, absolute: true })
+  for (const filePath of subdirSkills) {
+    const name = path.basename(path.dirname(filePath))
+    // Avoid duplicate if already found as root
+    if (!skills.some(s => s.name === name)) {
+      skills.push({ name, filePath })
+    }
+  }
+
+  // Pattern 3: {dir}/skills/*/SKILL.md (nested skills directory)
+  const nestedSkills = await glob('skills/*/SKILL.md', { cwd: dir, absolute: true })
+  for (const filePath of nestedSkills) {
+    const name = path.basename(path.dirname(filePath))
+    if (!skills.some(s => s.name === name)) {
+      skills.push({ name, filePath })
+    }
+  }
+
+  return skills
+}
+
+// =============================================================================
+// Frontmatter Injection
+// =============================================================================
+
+/**
+ * Add _prjct source tracking metadata to a skill's frontmatter
+ */
+function injectSourceMetadata(
+  content: string,
+  source: ParsedSource,
+  sha?: string
+): string {
+  const now = new Date().toISOString()
+  const prjctBlock = [
+    `_prjct:`,
+    `  sourceUrl: ${source.url}`,
+    `  sourceType: ${source.type}`,
+    `  installedAt: ${now}`,
+  ]
+  if (sha) {
+    prjctBlock.push(`  sha: ${sha}`)
+  }
+
+  // Check if file has existing frontmatter
+  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---/
+  const match = content.match(frontmatterRegex)
+
+  if (match) {
+    // Remove existing _prjct block if present
+    let frontmatter = match[1]
+    frontmatter = frontmatter.replace(/\n?_prjct:[\s\S]*?(?=\n[a-zA-Z]|\n---|\s*$)/g, '')
+
+    // Append _prjct block
+    const updatedFrontmatter = frontmatter.trimEnd() + '\n' + prjctBlock.join('\n')
+    return content.replace(frontmatterRegex, `---\n${updatedFrontmatter}\n---`)
+  }
+
+  // No frontmatter — add one
+  return `---\n${prjctBlock.join('\n')}\n---\n\n${content}`
+}
+
+// =============================================================================
+// Installation
+// =============================================================================
+
+/**
+ * Get the default install directory for skills
+ */
+function getInstallDir(): string {
+  return path.join(os.homedir(), '.claude', 'skills')
+}
+
+/**
+ * Install a single skill file to the target directory
+ */
+async function installSkillFile(
+  sourcePath: string,
+  name: string,
+  source: ParsedSource,
+  sha?: string
+): Promise<InstalledSkill> {
+  const installDir = getInstallDir()
+  const targetDir = path.join(installDir, name)
+  const targetPath = path.join(targetDir, 'SKILL.md')
+
+  // Read source content
+  const content = await fs.readFile(sourcePath, 'utf-8')
+
+  // Inject source metadata
+  const enrichedContent = injectSourceMetadata(content, source, sha)
+
+  // Write to target (ecosystem standard: {name}/SKILL.md)
+  await fs.mkdir(targetDir, { recursive: true })
+  await fs.writeFile(targetPath, enrichedContent, 'utf-8')
+
+  return {
+    name,
+    filePath: targetPath,
+    source,
+    sha,
+  }
+}
+
+/**
+ * Install skills from a GitHub repository
+ */
+async function installFromGitHub(source: ParsedSource): Promise<InstallResult> {
+  const result: InstallResult = { installed: [], skipped: [], errors: [] }
+
+  // Create temp directory
+  const tmpDir = path.join(os.tmpdir(), `prjct-skill-${Date.now()}`)
+
+  try {
+    // Clone with depth 1 for speed
+    const cloneUrl = `https://github.com/${source.owner}/${source.repo}.git`
+    await exec(`git clone --depth 1 ${cloneUrl} ${tmpDir}`, { timeout: 60_000 })
+
+    // Get the commit SHA
+    let sha: string | undefined
+    try {
+      const { stdout } = await exec('git rev-parse HEAD', { cwd: tmpDir, timeout: 5_000 })
+      sha = stdout.trim()
+    } catch {
+      // Non-critical
+    }
+
+    // Discover skills in the cloned repo
+    const discoveredSkills = await discoverSkills(tmpDir)
+
+    if (discoveredSkills.length === 0) {
+      result.errors.push(`No SKILL.md files found in ${source.owner}/${source.repo}`)
+      return result
+    }
+
+    // Filter to specific skill if requested
+    const skillsToInstall = source.skillName
+      ? discoveredSkills.filter(s => s.name === source.skillName)
+      : discoveredSkills
+
+    if (source.skillName && skillsToInstall.length === 0) {
+      result.errors.push(`Skill "${source.skillName}" not found in ${source.owner}/${source.repo}`)
+      return result
+    }
+
+    // Install each skill
+    for (const skill of skillsToInstall) {
+      try {
+        const installed = await installSkillFile(skill.filePath, skill.name, source, sha)
+
+        // Update lock file
+        const lockEntry: SkillLockEntry = {
+          name: skill.name,
+          source: {
+            type: 'github',
+            url: `${source.owner}/${source.repo}`,
+            sha,
+          },
+          installedAt: new Date().toISOString(),
+          filePath: installed.filePath,
+        }
+        await skillLock.addEntry(lockEntry)
+
+        result.installed.push(installed)
+      } catch (error) {
+        result.errors.push(`Failed to install ${skill.name}: ${(error as Error).message}`)
+      }
+    }
+  } finally {
+    // Clean up temp directory
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true })
+    } catch {
+      // Best effort cleanup
+    }
+  }
+
+  return result
+}
+
+/**
+ * Install skills from a local directory
+ */
+async function installFromLocal(source: ParsedSource): Promise<InstallResult> {
+  const result: InstallResult = { installed: [], skipped: [], errors: [] }
+  const localPath = source.localPath!
+
+  try {
+    await fs.access(localPath)
+  } catch {
+    result.errors.push(`Local path not found: ${localPath}`)
+    return result
+  }
+
+  const stat = await fs.stat(localPath)
+
+  if (stat.isFile()) {
+    // Single SKILL.md file
+    const name = path.basename(path.dirname(localPath))
+    try {
+      const installed = await installSkillFile(localPath, name, source)
+      const lockEntry: SkillLockEntry = {
+        name,
+        source: { type: 'local', url: localPath },
+        installedAt: new Date().toISOString(),
+        filePath: installed.filePath,
+      }
+      await skillLock.addEntry(lockEntry)
+      result.installed.push(installed)
+    } catch (error) {
+      result.errors.push(`Failed to install from ${localPath}: ${(error as Error).message}`)
+    }
+  } else {
+    // Directory — discover skills
+    const discoveredSkills = await discoverSkills(localPath)
+
+    if (discoveredSkills.length === 0) {
+      result.errors.push(`No SKILL.md files found in ${localPath}`)
+      return result
+    }
+
+    for (const skill of discoveredSkills) {
+      try {
+        const installed = await installSkillFile(skill.filePath, skill.name, source)
+        const lockEntry: SkillLockEntry = {
+          name: skill.name,
+          source: { type: 'local', url: localPath },
+          installedAt: new Date().toISOString(),
+          filePath: installed.filePath,
+        }
+        await skillLock.addEntry(lockEntry)
+        result.installed.push(installed)
+      } catch (error) {
+        result.errors.push(`Failed to install ${skill.name}: ${(error as Error).message}`)
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Remove an installed skill
+ */
+async function remove(name: string): Promise<boolean> {
+  const installDir = getInstallDir()
+
+  // Remove subdirectory format
+  const subdirPath = path.join(installDir, name)
+  try {
+    await fs.rm(subdirPath, { recursive: true, force: true })
+  } catch {
+    // May not exist in subdir format
+  }
+
+  // Remove flat file format
+  const flatPath = path.join(installDir, `${name}.md`)
+  try {
+    await fs.rm(flatPath, { force: true })
+  } catch {
+    // May not exist in flat format
+  }
+
+  // Remove from lock file
+  return skillLock.removeEntry(name)
+}
+
+// =============================================================================
+// Main Install Function
+// =============================================================================
+
+/**
+ * Install skills from a source string
+ *
+ * @param source - Source string (e.g., "owner/repo", "owner/repo@skill", "./path")
+ * @returns Installation result with installed, skipped, and error lists
+ */
+async function install(sourceStr: string): Promise<InstallResult> {
+  const source = parseSource(sourceStr)
+
+  switch (source.type) {
+    case 'github':
+      return installFromGitHub(source)
+    case 'local':
+      return installFromLocal(source)
+    default:
+      return {
+        installed: [],
+        skipped: [],
+        errors: [`Unsupported source type: ${source.type}`],
+      }
+  }
+}
+
+export const skillInstaller = {
+  install,
+  remove,
+  parseSource,
+  getInstallDir,
+}
+
+export default skillInstaller

package/core/services/skill-lock.ts

@@ -0,0 +1,132 @@
+/**
+ * Skill Lock File Service
+ *
+ * Manages a lock file that tracks remotely-installed skills for
+ * reproducibility and update detection.
+ *
+ * Lock file location: ~/.prjct-cli/skills/.skill-lock.json
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SkillLockSource {
+  type: 'github' | 'local' | 'registry'
+  url: string
+  sha?: string
+}
+
+export interface SkillLockEntry {
+  name: string
+  source: SkillLockSource
+  installedAt: string
+  filePath: string
+}
+
+export interface SkillLockFile {
+  version: 1
+  generatedAt: string
+  skills: Record<string, SkillLockEntry>
+}
+
+// =============================================================================
+// Lock File Service
+// =============================================================================
+
+const LOCK_FILE_NAME = '.skill-lock.json'
+
+function getLockFilePath(): string {
+  return path.join(os.homedir(), '.prjct-cli', 'skills', LOCK_FILE_NAME)
+}
+
+function createEmptyLockFile(): SkillLockFile {
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    skills: {},
+  }
+}
+
+/**
+ * Read the lock file, returning an empty lock file if it doesn't exist
+ */
+async function read(): Promise<SkillLockFile> {
+  try {
+    const content = await fs.readFile(getLockFilePath(), 'utf-8')
+    return JSON.parse(content) as SkillLockFile
+  } catch {
+    return createEmptyLockFile()
+  }
+}
+
+/**
+ * Write the lock file to disk
+ */
+async function write(lockFile: SkillLockFile): Promise<void> {
+  const lockPath = getLockFilePath()
+  await fs.mkdir(path.dirname(lockPath), { recursive: true })
+  lockFile.generatedAt = new Date().toISOString()
+  await fs.writeFile(lockPath, JSON.stringify(lockFile, null, 2), 'utf-8')
+}
+
+/**
+ * Add or update a skill entry in the lock file
+ */
+async function addEntry(entry: SkillLockEntry): Promise<void> {
+  const lockFile = await read()
+  lockFile.skills[entry.name] = entry
+  await write(lockFile)
+}
+
+/**
+ * Remove a skill entry from the lock file
+ */
+async function removeEntry(name: string): Promise<boolean> {
+  const lockFile = await read()
+  if (!(name in lockFile.skills)) return false
+  delete lockFile.skills[name]
+  await write(lockFile)
+  return true
+}
+
+/**
+ * Get a single skill entry
+ */
+async function getEntry(name: string): Promise<SkillLockEntry | null> {
+  const lockFile = await read()
+  return lockFile.skills[name] || null
+}
+
+/**
+ * Get all entries
+ */
+async function getAll(): Promise<Record<string, SkillLockEntry>> {
+  const lockFile = await read()
+  return lockFile.skills
+}
+
+/**
+ * Get the lock file path (for display purposes)
+ */
+function getPath(): string {
+  return getLockFilePath()
+}
+
+export const skillLock = {
+  read,
+  write,
+  addEntry,
+  removeEntry,
+  getEntry,
+  getAll,
+  getPath,
+}
+
+export default skillLock

package/core/services/skill-service.ts

@@ -83,9 +83,9 @@ class SkillService {
   /**
    * Get all skill directories in order of priority
    */
-  private getSkillDirs(projectPath?: string, provider?: AIProviderName): Array<{ dir: string; source: Skill['source']; isProviderSkill?: boolean }> {
+  private getSkillDirs(projectPath?: string, provider?: AIProviderName): Array<{ dir: string; source: Skill['source'] }> {
     const homeDir = process.env.HOME || process.env.USERPROFILE || '~'
-    const dirs: Array<{ dir: string; source: Skill['source']; isProviderSkill?: boolean }> = []
+    const dirs: Array<{ dir: string; source: Skill['source'] }> = []
 
     // Project skills (highest priority)
     if (projectPath) {
@@ -96,11 +96,11 @@ class SkillService {
     // Both use SKILL.md format, so skills are compatible
     if (provider) {
       const providerDir = provider === 'gemini' ? '.gemini' : '.claude'
-      dirs.push({ dir: path.join(homeDir, providerDir, 'skills'), source: 'global', isProviderSkill: true })
+      dirs.push({ dir: path.join(homeDir, providerDir, 'skills'), source: 'global' })
     } else {
       // Check both providers if no specific one is set
-      dirs.push({ dir: path.join(homeDir, '.claude', 'skills'), source: 'global', isProviderSkill: true })
-      dirs.push({ dir: path.join(homeDir, '.gemini', 'skills'), source: 'global', isProviderSkill: true })
+      dirs.push({ dir: path.join(homeDir, '.claude', 'skills'), source: 'global' })
+      dirs.push({ dir: path.join(homeDir, '.gemini', 'skills'), source: 'global' })
     }
 
     // prjct global skills
@@ -123,6 +123,9 @@ class SkillService {
       const id = fileToSkillId(filePath)
       const name = (metadata.name as string) || id
 
+      // Extract _prjct source tracking metadata if present
+      const prjctMeta = metadata._prjct as Record<string, unknown> | undefined
+
       return {
         id,
         name,
@@ -136,6 +139,12 @@ class SkillService {
           agent: metadata.agent as string,
           tags: metadata.tags as string[],
           version: metadata.version as string,
+          category: metadata.category as string,
+          author: metadata.author as string,
+          sourceUrl: prjctMeta?.sourceUrl as string,
+          sourceType: prjctMeta?.sourceType as SkillMetadata['sourceType'],
+          installedAt: prjctMeta?.installedAt as string,
+          sha: prjctMeta?.sha as string,
         },
       }
     } catch (_error) {
@@ -151,27 +160,27 @@ class SkillService {
     this.skills.clear()
     const dirs = this.getSkillDirs(projectPath, provider)
 
-    for (const { dir, source, isProviderSkill } of dirs) {
+    for (const { dir, source } of dirs) {
       try {
-        if (isProviderSkill) {
-          // Provider skills use SKILL.md in subdirectories
-          // e.g., ~/.claude/skills/my-skill/SKILL.md
-          const skillDirs = await glob('*/SKILL.md', { cwd: dir, absolute: true })
-          for (const file of skillDirs) {
-            const skill = await this.loadSkill(file, source)
-            if (skill && !this.skills.has(skill.id)) {
-              this.skills.set(skill.id, skill)
-            }
+        // Check both patterns in ALL skill directories:
+        // 1. Flat files: {dir}/{name}.md
+        // 2. Subdirectories: {dir}/{name}/SKILL.md (ecosystem standard)
+        const flatFiles = await glob('*.md', { cwd: dir, absolute: true })
+        const subdirFiles = await glob('*/SKILL.md', { cwd: dir, absolute: true })
+
+        // Load subdirectory skills first (ecosystem standard takes priority within same dir)
+        for (const file of subdirFiles) {
+          const skill = await this.loadSkill(file, source)
+          if (skill && !this.skills.has(skill.id)) {
+            this.skills.set(skill.id, skill)
           }
-        } else {
-          // Regular .md files in directory
-          const files = await glob('*.md', { cwd: dir, absolute: true })
-          for (const file of files) {
-            const skill = await this.loadSkill(file, source)
-            if (skill && !this.skills.has(skill.id)) {
-              // Don't override higher priority skills
-              this.skills.set(skill.id, skill)
-            }
+        }
+
+        // Then flat files (don't override subdirectory version)
+        for (const file of flatFiles) {
+          const skill = await this.loadSkill(file, source)
+          if (skill && !this.skills.has(skill.id)) {
+            this.skills.set(skill.id, skill)
           }
         }
       } catch (_error) {
@@ -256,6 +265,7 @@ class SkillService {
       project: [],
       global: [],
       builtin: [],
+      remote: [],
     }
 
     for (const skill of skills) {

package/core/types/services.ts

@@ -28,6 +28,11 @@ export interface SkillMetadata {
   version?: string
   category?: string
   author?: string
+  // Ecosystem compatibility fields
+  sourceUrl?: string
+  sourceType?: 'github' | 'local' | 'builtin' | 'registry'
+  installedAt?: string
+  sha?: string
 }
 
 export interface Skill {
@@ -35,7 +40,7 @@ export interface Skill {
   name: string
   description: string
   content: string
-  source: 'project' | 'global' | 'builtin'
+  source: 'project' | 'global' | 'builtin' | 'remote'
   filePath: string
   metadata: SkillMetadata
   path?: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {

package/templates/commands/skill.md

@@ -1,22 +1,26 @@
 ---
-allowed-tools: [Read, Glob]
+allowed-tools: [Read, Glob, Bash]
 description: 'List, search, and invoke skills'
 timestamp-rule: 'None'
-architecture: 'Skill discovery and execution'
+architecture: 'Skill discovery, installation, and execution'
 ---
 
 # /p:skill - Skill Management
 
-List, search, and invoke reusable skills.
+List, search, install, and invoke reusable skills.
 
 ## Usage
 
 ```
-/p:skill                    # List all skills
-/p:skill list               # List all skills
-/p:skill search <query>     # Search skills
-/p:skill show <id>          # Show skill details
-/p:skill invoke <id>        # Invoke a skill
+/p:skill                        # List all skills
+/p:skill list                   # List all skills
+/p:skill search <query>         # Search skills
+/p:skill show <id>              # Show skill details
+/p:skill invoke <id>            # Invoke a skill
+/p:skill add <source>           # Install skill from remote source
+/p:skill remove <name>          # Remove an installed skill
+/p:skill init <name>            # Scaffold a new skill
+/p:skill check                  # Check for available updates
 ```
 
 ## Flow
@@ -24,11 +28,14 @@ List, search, and invoke reusable skills.
 ### List Skills (`/p:skill` or `/p:skill list`)
 
 1. Load skills from all sources:
-   - Project: `.prjct/skills/*.md`
-   - Global: `~/.prjct-cli/skills/*.md`
+   - Project: `.prjct/skills/*.md` and `.prjct/skills/*/SKILL.md`
+   - Provider: `~/.claude/skills/*/SKILL.md` and `~/.claude/skills/*.md`
+   - Global: `~/.prjct-cli/skills/*.md` and `~/.prjct-cli/skills/*/SKILL.md`
    - Built-in: `templates/skills/*.md`
 
-2. Output grouped by source:
+2. Check lock file at `~/.prjct-cli/skills/.skill-lock.json` for source info
+
+3. Output grouped by source:
 
 ```
 ## Available Skills
@@ -36,13 +43,13 @@ List, search, and invoke reusable skills.
 ### Project Skills
 - **custom-deploy** - Deploy to staging server
 
-### Global Skills
+### Global Skills (Provider)
+- **frontend-design** - Create production-grade UIs [github: vercel-labs/skills]
 - **my-template** - Personal code template
 
 ### Built-in Skills
 - **code-review** - Review code for quality
 - **refactor** - Refactor code structure
-- **debug** - Systematic debugging
 ```
 
 ### Search Skills (`/p:skill search <query>`)
@@ -55,14 +62,17 @@ List, search, and invoke reusable skills.
 
 1. Load skill by ID
 2. Display metadata and content
+3. If remotely installed, show source tracking info
 
 ```
-## Skill: code-review
+## Skill: frontend-design
 
-**Description:** Review code for quality
-**Source:** builtin
-**Tags:** review, quality, security
-**Agent:** general
+**Description:** Create production-grade frontend interfaces
+**Source:** global (github: vercel-labs/skills)
+**Tags:** frontend, design, ui
+**Version:** 1.0.0
+**Installed:** 2026-01-28T12:00:00.000Z
+**SHA:** abc123
 
 ### Content
 [Full skill prompt content]
@@ -74,9 +84,122 @@ List, search, and invoke reusable skills.
 2. Return skill content for execution
 3. The skill content becomes the prompt
 
+### Add Skill (`/p:skill add <source>`)
+
+Install skills from remote sources.
+
+**Supported source formats:**
+- `owner/repo` — Clone GitHub repo, install all discovered skills
+- `owner/repo@skill-name` — Install specific skill from GitHub repo
+- `./local-path` — Install from local directory
+
+**Install flow:**
+1. Parse source string
+2. For GitHub: `git clone --depth 1` to temp dir (60s timeout)
+3. Discover SKILL.md files (scans `*/SKILL.md` and `skills/*/SKILL.md`)
+4. Copy to `~/.claude/skills/{name}/SKILL.md` (ecosystem standard format)
+5. Add `_prjct` metadata block to frontmatter (sourceUrl, sha, installedAt)
+6. Update lock file at `~/.prjct-cli/skills/.skill-lock.json`
+7. Clean up temp dir
+
+**Example:**
+```
+p. skill add vercel-labs/skills
+p. skill add my-org/custom-skills@api-designer
+p. skill add ./my-local-skill
+```
+
+**Output:**
+```
+✅ Installed 3 skills from vercel-labs/skills
+
+- frontend-design → ~/.claude/skills/frontend-design/SKILL.md
+- find-skills → ~/.claude/skills/find-skills/SKILL.md
+- code-review → ~/.claude/skills/code-review/SKILL.md
+
+Lock file updated: ~/.prjct-cli/skills/.skill-lock.json
+```
+
+### Remove Skill (`/p:skill remove <name>`)
+
+1. Remove skill directory from `~/.claude/skills/{name}/`
+2. Also remove flat file if it exists (`~/.claude/skills/{name}.md`)
+3. Remove entry from lock file
+4. Confirm removal
+
+**Output:**
+```
+✅ Removed skill: frontend-design
+
+Deleted: ~/.claude/skills/frontend-design/
+Lock file updated.
+```
+
+### Init Skill (`/p:skill init <name>`)
+
+Scaffold a new skill in the project.
+
+1. Create `.prjct/skills/{name}/SKILL.md` with template frontmatter
+2. Open for editing
+
+**Template:**
+```markdown
+---
+name: {name}
+description: TODO - describe what this skill does
+agent: general
+tags: []
+version: 1.0.0
+author: {detected-author}
+---
+
+# {Name} Skill
+
+## Purpose
+
+Describe what this skill helps with.
+
+## Instructions
+
+Step-by-step instructions for the AI agent...
+```
+
+### Check Updates (`/p:skill check`)
+
+Compare lock file SHAs with remote repositories to detect available updates.
+
+1. Read lock file entries
+2. For each GitHub-sourced skill, run `git ls-remote` to get latest SHA
+3. Compare with stored SHA
+4. Report skills with available updates (no auto-update)
+
+**Output:**
+```
+## Skill Update Check
+
+- **frontend-design** (vercel-labs/skills) — Update available
+  Current: abc123 → Latest: def456
+- **code-review** (vercel-labs/skills) — Up to date
+- **my-local-skill** (local) — Skipped (local source)
+
+1 update available. Run `p. skill add <source>` to update.
+```
+
 ## Skill File Format
 
-Skills are markdown files with frontmatter:
+Skills are markdown files with frontmatter. Two formats are supported:
+
+### Subdirectory Format (Ecosystem Standard)
+```
+~/.claude/skills/my-skill/SKILL.md
+```
+
+### Flat Format (Legacy)
+```
+~/.claude/skills/my-skill.md
+```
+
+### Frontmatter Schema
 
 ```markdown
 ---
@@ -85,6 +208,13 @@ description: What the skill does
 agent: general
 tags: [tag1, tag2]
 version: 1.0.0
+author: Author Name
+category: development
+_prjct:
+  sourceUrl: https://github.com/owner/repo
+  sourceType: github
+  installedAt: 2026-01-28T12:00:00.000Z
+  sha: abc123
 ---
 
 # Skill Content
@@ -94,11 +224,30 @@ The actual prompt/instructions...
 
 ## Creating Custom Skills
 
-### Project Skill
-Create `.prjct/skills/my-skill.md`
-
-### Global Skill
-Create `~/.prjct-cli/skills/my-skill.md`
+### Project Skill (repo-specific)
+Create `.prjct/skills/my-skill/SKILL.md` or `.prjct/skills/my-skill.md`
+
+### Global Skill (all projects)
+Create `~/.claude/skills/my-skill/SKILL.md` or `~/.prjct-cli/skills/my-skill.md`
+
+## Lock File
+
+Installed skills are tracked in `~/.prjct-cli/skills/.skill-lock.json`:
+
+```json
+{
+  "version": 1,
+  "generatedAt": "2026-01-28T...",
+  "skills": {
+    "frontend-design": {
+      "name": "frontend-design",
+      "source": { "type": "github", "url": "vercel-labs/skills", "sha": "abc123" },
+      "installedAt": "2026-01-28T...",
+      "filePath": "~/.claude/skills/frontend-design/SKILL.md"
+    }
+  }
+}
+```
 
 ## Output Format
 
@@ -106,5 +255,5 @@ Create `~/.prjct-cli/skills/my-skill.md`
 ## Skills ({count} total)
 
 ### {source}
-- **{name}** ({id}): {description}
+- **{name}** ({id}): {description} [{sourceInfo}]
 ```