@vox-ai-app/skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnav Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@vox-ai-app/skills",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "AgentSkills-compatible skill loader for Vox — load SKILL.md folders, parse frontmatter, inject into LLM prompts",
+  "main": "./src/index.js",
+  "private": false,
+  "exports": {
+    ".": "./src/index.js",
+    "./loader": "./src/loader.js",
+    "./parser": "./src/parser.js",
+    "./prompt": "./src/prompt.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vox-ai-app/vox"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {}
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { parseFrontmatter } from './parser.js'
+export { loadSkillsFromDir, loadAllSkills, resolveDefaultSkillDirs } from './loader.js'
+export { formatSkillsForPrompt, formatSkillBody } from './prompt.js'

package/src/loader.js

@@ -0,0 +1,117 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseFrontmatter } from './parser.js'
+
+function isPathInside(parent, child) {
+  const rel = path.relative(parent, child)
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel)
+}
+
+function loadSingleSkill(skillDir, source, rootReal, maxBytes) {
+  const skillPath = path.join(skillDir, 'SKILL.md')
+  let raw
+  try {
+    const stat = fs.statSync(skillPath)
+    if (maxBytes && stat.size > maxBytes) return null
+    raw = fs.readFileSync(skillPath, 'utf8')
+  } catch {
+    return null
+  }
+
+  const resolved = fs.realpathSync(skillPath)
+  if (!isPathInside(rootReal, resolved) && resolved !== rootReal) {
+    const skillReal = fs.realpathSync(skillDir)
+    if (!isPathInside(rootReal, skillReal) && skillReal !== rootReal) return null
+  }
+
+  const { fields, body } = parseFrontmatter(raw)
+  const fallbackName = path.basename(skillDir).trim()
+  const name = fields.name?.trim() || fallbackName
+  const description = fields.description?.trim()
+  if (!name || !description) return null
+
+  const metadata = fields.metadata || null
+  const userInvocable = fields['user-invocable'] !== 'false'
+  const disableModelInvocation = fields['disable-model-invocation'] === 'true'
+
+  return {
+    name,
+    description,
+    filePath: path.resolve(skillPath),
+    baseDir: path.resolve(skillDir),
+    body,
+    source,
+    metadata,
+    userInvocable,
+    disableModelInvocation
+  }
+}
+
+function listSkillDirs(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+      .map(e => path.join(dir, e.name))
+      .sort()
+  } catch {
+    return []
+  }
+}
+
+export function loadSkillsFromDir(dir, source, opts = {}) {
+  const maxBytes = opts.maxBytes || 256_000
+  const maxSkills = opts.maxSkills || 200
+  let rootReal
+  try {
+    rootReal = fs.realpathSync(path.resolve(dir))
+  } catch {
+    return []
+  }
+
+  const single = loadSingleSkill(rootReal, source, rootReal, maxBytes)
+  if (single) return [single]
+
+  const candidates = listSkillDirs(rootReal).slice(0, maxSkills)
+  const skills = []
+  for (const candidate of candidates) {
+    const skill = loadSingleSkill(candidate, source, rootReal, maxBytes)
+    if (skill) skills.push(skill)
+  }
+  return skills
+}
+
+export function loadAllSkills(skillDirs, opts = {}) {
+  const maxTotal = opts.maxTotal || 150
+  const all = []
+  const seen = new Set()
+
+  for (const { dir, source } of skillDirs) {
+    const skills = loadSkillsFromDir(dir, source, opts)
+    for (const skill of skills) {
+      if (seen.has(skill.name)) continue
+      seen.add(skill.name)
+      all.push(skill)
+      if (all.length >= maxTotal) return all
+    }
+  }
+  return all
+}
+
+export function resolveDefaultSkillDirs(workspace) {
+  const home = process.env.HOME || process.env.USERPROFILE || ''
+  const dirs = []
+
+  if (workspace) {
+    dirs.push({ dir: path.join(workspace, 'skills'), source: 'workspace' })
+    dirs.push({ dir: path.join(workspace, '.agents', 'skills'), source: 'project-agent' })
+  }
+
+  if (home) {
+    dirs.push({ dir: path.join(home, '.agents', 'skills'), source: 'personal-agent' })
+    dirs.push({ dir: path.join(home, '.vox', 'skills'), source: 'managed' })
+  }
+
+  return dirs.filter(d => {
+    try { return fs.statSync(d.dir).isDirectory() } catch { return false }
+  })
+}

package/src/parser.js

@@ -0,0 +1,73 @@
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+function parseYamlLine(line) {
+  const idx = line.indexOf(':')
+  if (idx === -1) return null
+  const key = line.slice(0, idx).trim()
+  let value = line.slice(idx + 1).trim()
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+    value = value.slice(1, -1)
+  }
+  return { key, value }
+}
+
+export function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE)
+  if (!match) return { fields: {}, body: content }
+
+  const raw = match[1]
+  const fields = {}
+  let metadataJson = null
+  let collectingMetadata = false
+  let metadataBuf = ''
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+
+    if (collectingMetadata) {
+      metadataBuf += trimmed
+      let depth = 0
+      for (const ch of metadataBuf) {
+        if (ch === '{') depth++
+        if (ch === '}') depth--
+      }
+      if (depth <= 0) {
+        collectingMetadata = false
+        try {
+          metadataJson = JSON.parse(metadataBuf)
+        } catch {
+          metadataJson = null
+        }
+      }
+      continue
+    }
+
+    if (trimmed.startsWith('metadata:')) {
+      const rest = trimmed.slice('metadata:'.length).trim()
+      if (rest.startsWith('{')) {
+        metadataBuf = rest
+        let depth = 0
+        for (const ch of metadataBuf) {
+          if (ch === '{') depth++
+          if (ch === '}') depth--
+        }
+        if (depth <= 0) {
+          try { metadataJson = JSON.parse(metadataBuf) } catch { /* skip */ }
+        } else {
+          collectingMetadata = true
+        }
+      }
+      continue
+    }
+
+    if (line.startsWith('  ') || line.startsWith('\t')) continue
+
+    const parsed = parseYamlLine(trimmed)
+    if (parsed) fields[parsed.key] = parsed.value
+  }
+
+  if (metadataJson) fields.metadata = metadataJson
+
+  const body = content.slice(match[0].length).trim()
+  return { fields, body }
+}

package/src/prompt.js

@@ -0,0 +1,47 @@
+import os from 'node:os'
+import path from 'node:path'
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;')
+}
+
+function compactPath(filePath) {
+  const home = os.homedir()
+  if (!home) return filePath
+  const prefix = home.endsWith(path.sep) ? home : home + path.sep
+  return filePath.startsWith(prefix) ? '~/' + filePath.slice(prefix.length) : filePath
+}
+
+export function formatSkillsForPrompt(skills) {
+  const visible = skills.filter(s => !s.disableModelInvocation)
+  if (visible.length === 0) return ''
+
+  const lines = [
+    '',
+    'The following skills provide specialized instructions for specific tasks.',
+    'When the task matches a skill description, read its file to get detailed instructions.',
+    '',
+    '<available_skills>'
+  ]
+
+  for (const skill of visible) {
+    lines.push('  <skill>')
+    lines.push(`    <name>${escapeXml(skill.name)}</name>`)
+    lines.push(`    <description>${escapeXml(skill.description)}</description>`)
+    lines.push(`    <location>${escapeXml(compactPath(skill.filePath))}</location>`)
+    lines.push('  </skill>')
+  }
+
+  lines.push('</available_skills>')
+  return lines.join('\n')
+}
+
+export function formatSkillBody(skill) {
+  if (!skill.body) return ''
+  return `\n\n--- Skill: ${skill.name} ---\n${skill.body}\n--- End Skill ---`
+}