Preserve reviewed skill install hardening after rebase

Rebasing PR #1162 onto current main flattened an earlier merge commit that carried reviewed Skill Hub hardening and regression coverage. This restores those final-tree changes as a normal linear commit so the rebased PR keeps the same behavior reviewers approved without retaining merge commits or mainline noise.

Constraint: Keep the PR branch linear for maintainer review while preserving the reviewed final tree from the conflict-resolved integration branch.

Rejected: Push the plain rebase result | it would drop registry sha256/version/trust metadata handling and associated tests from the reviewed PR state.

Confidence: high

Scope-risk: narrow

Directive: Do not remove the registry sha256 requirement or install-path regression tests without another security review.

Tested: final tree compared against fix-pr-1162-conflicts before verification

Author: anandh8x

src/cli/handlers/skills.test.ts

@@ -384,6 +384,8 @@ test.serial('installs a registry skill by id from a local registry file', async
           path: 'skills/sample-skill/SKILL.md',
           homepage: 'https://github.com/Gitlawb/openclaude-skills/tree/main/skills/sample-skill',
           sha256: sha256OfSkillSource(VALID_SKILL),
+          min_openclaude_version: '0.1.0',
+          tools_required: ['Read', 'Bash'],
         },
       ]),
       'utf8',
@@ -399,9 +401,86 @@ test.serial('installs a registry skill by id from a local registry file', async
         join(cwd, '.openclaude', 'skills', 'sample-skill', 'skill.json'),
         'utf8',
       ),
-    ) as { trust: string; sha256: string }
+    ) as {
+      trust: string
+      sha256: string
+      min_openclaude_version: string
+      tools_required: string[]
+    }
     assert.equal(installedMetadata.trust, 'official')
     assert.equal(installedMetadata.sha256, sha256OfSkillSource(VALID_SKILL))
+    assert.equal(installedMetadata.min_openclaude_version, '0.1.0')
+    assert.deepEqual(installedMetadata.tools_required, ['Read', 'Bash'])
+  })
+})
+
+test.serial('rejects registry skills without a sha256 pin', async () => {
+  await withTempDir(async tempDir => {
+    const cwd = join(tempDir, 'project')
+    const sourceDir = writeSkillDir(join(tempDir, 'registry-source'))
+    const registryPath = join(tempDir, 'registry.json')
+    mkdirSync(cwd, { recursive: true })
+    writeFileSync(
+      registryPath,
+      JSON.stringify([
+        {
+          id: 'gitlawb/sample-skill',
+          name: 'sample-skill',
+          title: 'Sample Skill',
+          description: 'Sample skill used by install tests.',
+          trust: 'official',
+          version: '0.1.0',
+          license: 'MIT',
+          author: 'OpenClaude Tests',
+          source: join(sourceDir, 'SKILL.md'),
+        },
+      ]),
+      'utf8',
+    )
+
+    await skillsInstallHandler('sample-skill', {
+      projectDir: cwd,
+      registry: registryPath,
+    })
+
+    assert.equal(process.exitCode, 1)
+    assert.equal(existsSync(join(cwd, '.openclaude', 'skills')), false)
+  })
+})
+
+test.serial('rejects registry skills that require a newer OpenClaude version', async () => {
+  await withTempDir(async tempDir => {
+    const cwd = join(tempDir, 'project')
+    const sourceDir = writeSkillDir(join(tempDir, 'registry-source'))
+    const registryPath = join(tempDir, 'registry.json')
+    mkdirSync(cwd, { recursive: true })
+    writeFileSync(
+      registryPath,
+      JSON.stringify([
+        {
+          id: 'gitlawb/sample-skill',
+          name: 'sample-skill',
+          title: 'Sample Skill',
+          description: 'Sample skill used by install tests.',
+          trust: 'official',
+          version: '0.1.0',
+          license: 'MIT',
+          author: 'OpenClaude Tests',
+          source: join(sourceDir, 'SKILL.md'),
+          sha256: sha256OfSkillSource(VALID_SKILL),
+          min_openclaude_version: '999.0.0',
+        },
+      ]),
+      'utf8',
+    )
+
+    await skillsInstallHandler('sample-skill', {
+      projectDir: cwd,
+      registry: registryPath,
+    })
+
+    assert.equal(process.exitCode, 1)
+    assert.equal(existsSync(join(cwd, '.openclaude', 'skills')), false)
   })
 })
 

src/cli/handlers/skillsInstall.ts

@@ -2,10 +2,12 @@ import { createHash } from 'crypto'
 import { cp, mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'fs/promises'
 import { tmpdir } from 'os'
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'path'
+import { coerce, lt } from 'semver'
 import { getCwd } from '../../utils/cwd.js'
 import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
 import { getDisplayPath } from '../../utils/file.js'
 import { parseFrontmatter } from '../../utils/frontmatterParser.js'
+import { publicBuildVersion } from '../../utils/version.js'
 import { validateSkillPath } from './skillsValidation.js'
 
 export type InstallOptions = {
@@ -28,6 +30,8 @@ type SkillRegistryEntry = {
   path?: unknown
   homepage?: unknown
   sha256?: unknown
+  min_openclaude_version?: unknown
+  tools_required?: unknown
   category?: unknown
   tags?: unknown
   author?: unknown
@@ -147,6 +151,8 @@ function registryMetadata(entry: SkillRegistryEntry): Record<string, unknown> {
     'path',
     'homepage',
     'sha256',
+    'min_openclaude_version',
+    'tools_required',
   ] as const) {
     const value = entry[key]
     if (value !== undefined) metadata[key] = value
@@ -159,6 +165,63 @@ function sha256OfSkillSource(text: string): string {
   return createHash('sha256').update(normalized, 'utf8').digest('hex')
 }
 
+function stringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === 'string' && item.trim() !== '')
+}
+
+function requireRegistrySha256(entry: SkillRegistryEntry, spec: string): string {
+  if (typeof entry.sha256 !== 'string' || entry.sha256.trim() === '') {
+    throw new Error(
+      `Registry entry "${spec}" is missing sha256. Refusing to install an unpinned skill.`,
+    )
+  }
+  return entry.sha256.trim()
+}
+
+function assertCompatibleOpenClaudeVersion(entry: SkillRegistryEntry, spec: string): string | undefined {
+  if (
+    typeof entry.min_openclaude_version !== 'string' ||
+    entry.min_openclaude_version.trim() === ''
+  ) {
+    return undefined
+  }
+
+  const minimum = entry.min_openclaude_version.trim()
+  const current = coerce(publicBuildVersion)
+  const required = coerce(minimum)
+
+  if (!current || !required) {
+    throw new Error(
+      `Registry entry "${spec}" has an invalid min_openclaude_version value: ${minimum}.`,
+    )
+  }
+
+  if (lt(current, required)) {
+    throw new Error(
+      `Skill "${spec}" requires OpenClaude ${required.version} or newer. Current version is ${current.version}.`,
+    )
+  }
+
+  return minimum
+}
+
+function trustInstallWarning(trust: string): string | null {
+  if (trust === 'official') {
+    return null
+  }
+  if (trust === 'verified') {
+    return 'Warning: this verified community skill was reviewed, but is not maintained as an official OpenClaude skill.'
+  }
+  if (trust === 'community') {
+    return 'Warning: this community skill passed registry validation, but may not be deeply reviewed or maintained by OpenClaude maintainers.'
+  }
+  if (trust === 'deprecated') {
+    return 'Warning: this skill is marked deprecated. Install only if you intentionally need this older workflow.'
+  }
+  return `Warning: this skill has trust tier "${trust}". Review SKILL.md before using it.`
+}
+
 function getSkillNameFromMarkdown(markdown: string, fallback: string): string {
   try {
     const { frontmatter } = parseFrontmatter(markdown, 'SKILL.md')
@@ -265,6 +328,8 @@ async function prepareInstallCandidate(
   skillName: string
   sourceDescription: string
   trust: string
+  toolsRequired: string[]
+  minOpenClaudeVersion?: string
 }> {
   if (!isUrl(spec) && (await pathExists(resolve(spec)))) {
     const sourcePath = resolve(spec)
@@ -287,6 +352,7 @@ async function prepareInstallCandidate(
         skillName,
         sourceDescription: getDisplayPath(sourcePath),
         trust: 'local',
+        toolsRequired: [],
       }
     }
 
@@ -297,6 +363,7 @@ async function prepareInstallCandidate(
       ...prepared,
       sourceDescription: getDisplayPath(sourcePath),
       trust: 'local',
+      toolsRequired: [],
     }
   }
 
@@ -308,6 +375,7 @@ async function prepareInstallCandidate(
       ...prepared,
       sourceDescription: spec,
       trust: 'url',
+      toolsRequired: [],
     }
   }
 
@@ -316,14 +384,14 @@ async function prepareInstallCandidate(
     throw new Error(`Skill "${spec}" was not found in the registry.`)
   }
 
+  const expectedSha256 = requireRegistrySha256(entry, spec)
+  const minOpenClaudeVersion = assertCompatibleOpenClaudeVersion(entry, spec)
   const markdown = await readSourceText(entry.source)
-  if (typeof entry.sha256 === 'string') {
-    const actual = sha256OfSkillSource(markdown)
-    if (actual !== entry.sha256) {
-      throw new Error(
-        `Registry checksum mismatch for "${spec}". Expected ${entry.sha256}, got ${actual}.`,
-      )
-    }
+  const actual = sha256OfSkillSource(markdown)
+  if (actual !== expectedSha256) {
+    throw new Error(
+      `Registry checksum mismatch for "${spec}". Expected ${expectedSha256}, got ${actual}.`,
+    )
   }
 
   const fallbackName =
@@ -337,6 +405,8 @@ async function prepareInstallCandidate(
     ...prepared,
     sourceDescription: entry.source,
     trust: typeof entry.trust === 'string' ? entry.trust : 'registry',
+    toolsRequired: stringArray(entry.tools_required),
+    minOpenClaudeVersion,
   }
 }
 
@@ -373,6 +443,16 @@ export async function skillsInstallHandler(
     console.log(`Installing skill "${candidate.skillName}"`)
     console.log(`Source: ${candidate.sourceDescription}`)
     console.log(`Trust: ${candidate.trust}`)
+    const trustWarning = trustInstallWarning(candidate.trust)
+    if (trustWarning) {
+      console.warn(trustWarning)
+    }
+    if (candidate.toolsRequired.length > 0) {
+      console.log(`Tools required: ${candidate.toolsRequired.join(', ')}`)
+    }
+    if (candidate.minOpenClaudeVersion) {
+      console.log(`Requires OpenClaude: >= ${candidate.minOpenClaudeVersion}`)
+    }
     console.log(`Target: ${getDisplayPath(targetDir)}`)
 
     await mkdir(root, { recursive: true })

src/skills/loadSkillsDir.test.ts

@@ -111,6 +111,7 @@ test('loads flat and nested skills with colon namespaces', async () => {
         process.env.CLAUDE_CONFIG_DIR = originalConfigDir
       }
       clearSkillCaches()
+      setAllowedSettingSources(originalSources)
       rmSync(configDir, { recursive: true, force: true })
     } finally {
       releaseSharedMutationLock()

src/utils/knowledgeGraph.stress.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, beforeEach, afterEach, afterAll } from 'bun:test'
+import { describe, expect, it, beforeEach, afterEach } from 'bun:test'
 import {
   addGlobalEntity,
   addGlobalSummary,
@@ -18,8 +18,7 @@ import { getFsImplementation } from './fsOperations.js'
 describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
   const originalConfigDir = process.env.CLAUDE_CONFIG_DIR
   const originalOrama = process.env.OPENCLAUDE_KNOWLEDGE_ORAMA
-  const configDir = mkdtempSync(join(tmpdir(), 'openclaude-stress-'))
-  const cwd = getFsImplementation().cwd()
+  let configDir: string | undefined
 
   const removeDirWithRetry = (dir: string) => {
     for (let attempt = 0; attempt < 5; attempt++) {
@@ -47,6 +46,7 @@ describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
 
   beforeEach(async () => {
     await acquireEnvMutex()
+    configDir = mkdtempSync(join(tmpdir(), 'openclaude-stress-'))
     process.env.CLAUDE_CONFIG_DIR = configDir
     process.env.OPENCLAUDE_KNOWLEDGE_ORAMA = '1'
     setClaudeConfigHomeDirForTesting(configDir)
@@ -69,14 +69,18 @@ describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
       }
       setClaudeConfigHomeDirForTesting(undefined)
     } finally {
-      releaseEnvMutex()
+      const dirToRemove = configDir
+      configDir = undefined
+      try {
+        if (dirToRemove) {
+          removeDirWithRetry(dirToRemove)
+        }
+      } finally {
+        releaseEnvMutex()
+      }
     }
   })
 
-  afterAll(() => {
-    removeDirWithRetry(configDir)
-  })
-
   it('handles high-volume entity insertion (Stress Test)', async () => {
     const count = 50
 
@@ -109,6 +113,7 @@ describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
     // 1. Create a valid DB
     await addGlobalEntity('type', 'valid', { val: '1' })
     const { getOramaPersistencePath } = await import('./knowledgeGraph.js')
+    const cwd = getFsImplementation().cwd()
     const oramaPath = getOramaPersistencePath(cwd)
     expect(existsSync(oramaPath)).toBe(true)
 
@@ -128,6 +133,8 @@ describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
     const { readdirSync } = await import('fs')
     // Search recursively from the actual Orama location. The config home can
     // be redirected by other tests, but the persisted file path is authoritative.
+    const projectDir = dirname(oramaPath)
+    expect(existsSync(projectDir)).toBe(true)
     const findCorrupted = (dir: string): boolean => {
       const entries = readdirSync(dir, { withFileTypes: true })
       for (const entry of entries) {
@@ -139,7 +146,7 @@ describe('KnowledgeGraph Phase 1 Stress & Edge Cases', () => {
       }
       return false
     }
-    expect(findCorrupted(dirname(oramaPath))).toBe(true)
+    expect(findCorrupted(projectDir)).toBe(true)
   })
 
   it('maintains consistency between JSON and Orama', async () => {