alpaki-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alpaki
+
+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/README.md

@@ -0,0 +1,66 @@
+# alpaki-skills
+
+CLI oficial de [Alpaki](https://alpaki.app) para instalar skills en **Cursor** o **Claude Code**.
+
+```bash
+npx alpaki-skills@latest --skill creative-design/3d-web-experience
+```
+
+## Qué hace
+
+1. Descarga la skill desde la API de Alpaki (`api.alpaki.app`).
+2. La guarda como `SKILL.md` en:
+   - Cursor: `./.cursor/skills/<slug>/SKILL.md`
+   - Claude: `./.claude/skills/<slug>/SKILL.md` (`--tool claude`)
+
+No empaqueta las ~800 skills en el npm: se resuelven on-demand, igual que el catálogo web.
+
+## Uso
+
+```bash
+# Instalar una skill (mismo comando que muestra alpaki.app/skills)
+npx alpaki-skills@latest --skill creative-design/3d-web-experience
+
+# Atajo sin flag
+npx alpaki-skills@latest development/api-design
+
+# Listar / buscar
+npx alpaki-skills@latest list
+npx alpaki-skills@latest search "frontend"
+npx alpaki-skills@latest list --category development
+
+# Claude Code
+npx alpaki-skills@latest --skill git/commit --tool claude
+
+# Destino custom o global
+npx alpaki-skills@latest --skill utilities/summarize --dir ./skills
+npx alpaki-skills@latest --skill utilities/summarize --global
+```
+
+## API local / staging
+
+```bash
+ALPAKI_API_BASE=http://localhost:8881 npx alpaki-skills --skill creative-design/3d-web-experience
+# o
+npx alpaki-skills --skill creative-design/3d-web-experience --api http://localhost:8881
+```
+
+## Publicar en npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+Después de publicar, `npx alpaki-skills@latest` funcionará para cualquiera.
+
+## Desarrollo
+
+```bash
+npm start -- --help
+npm start -- --skill creative-design/3d-web-experience --api http://localhost:8881
+```
+
+## Licencia
+
+MIT. El contenido de cada skill conserva la atribución del origen (claude-code-templates / davila7) cuando aplica.

package/bin/alpaki-skills.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from '../lib/cli.js'
+
+runCli(process.argv.slice(2)).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`\nError: ${message}\n`)
+  process.exitCode = 1
+})

package/lib/api.js

@@ -0,0 +1,108 @@
+const DEFAULT_API_BASE = 'https://api.alpaki.app'
+
+/**
+ * @param {string} raw
+ */
+export function resolveSkillPath(raw) {
+  const value = String(raw || '').trim().replace(/^\/+|\/+$/g, '')
+  if (!value) {
+    throw new Error('Debes indicar --skill categoria/slug (ej. creative-design/3d-web-experience).')
+  }
+
+  const parts = value.split('/').filter(Boolean)
+  if (parts.length === 1) {
+    return { category: '', slug: parts[0], path: parts[0] }
+  }
+
+  if (parts.length !== 2) {
+    throw new Error(`Ruta de skill inválida: "${raw}". Usa categoria/slug.`)
+  }
+
+  return {
+    category: parts[0],
+    slug: parts[1],
+    path: `${parts[0]}/${parts[1]}`,
+  }
+}
+
+/**
+ * @param {{ category: string, slug: string, path: string }} skillPath
+ * @param {{ apiBase?: string }} [options]
+ */
+export async function fetchSkill(skillPath, options = {}) {
+  const apiBase = normalizeApiBase(options.apiBase)
+  const bySlugUrl = `${apiBase}/wp-json/ae/v1/headless/skills/${encodeURIComponent(skillPath.slug)}`
+
+  const skill = await getJson(bySlugUrl)
+  if (!skill?.slug) {
+    throw new Error(`No se encontró la skill "${skillPath.path}" en Alpaki.`)
+  }
+
+  if (skillPath.category && skill.sourcePath && skill.sourcePath !== skillPath.path) {
+    // Si el usuario pasó categoria/slug, validamos que coincida con la fuente.
+    if (!String(skill.sourcePath).endsWith(`/${skillPath.slug}`)) {
+      throw new Error(
+        `La skill "${skill.slug}" existe, pero no coincide con "${skillPath.path}". Fuente: ${skill.sourcePath}`,
+      )
+    }
+  }
+
+  return skill
+}
+
+/**
+ * @param {{ search?: string, category?: string, page?: number, perPage?: number, apiBase?: string }} filters
+ */
+export async function fetchSkillsCatalog(filters = {}) {
+  const apiBase = normalizeApiBase(filters.apiBase)
+  const params = new URLSearchParams()
+  if (filters.search) params.set('search', filters.search)
+  if (filters.category) params.set('category', filters.category)
+  if (filters.page) params.set('page', String(filters.page))
+  if (filters.perPage) params.set('perPage', String(filters.perPage))
+  const query = params.toString()
+  const url = `${apiBase}/wp-json/ae/v1/headless/skills${query ? `?${query}` : ''}`
+  return getJson(url)
+}
+
+/**
+ * @param {string} [apiBase]
+ */
+function normalizeApiBase(apiBase) {
+  const fromEnv = process.env.ALPAKI_API_BASE || process.env.ALPAPI_API_BASE || ''
+  const base = String(apiBase || fromEnv || DEFAULT_API_BASE).replace(/\/$/, '')
+  return base
+}
+
+/**
+ * @param {string} url
+ */
+async function getJson(url) {
+  let response
+  try {
+    response = await fetch(url, {
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'alpaki-skills-cli/1.0',
+      },
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new Error(`No se pudo conectar con Alpaki (${url}): ${reason}`)
+  }
+
+  const text = await response.text()
+  let data
+  try {
+    data = text ? JSON.parse(text) : null
+  } catch {
+    throw new Error(`Respuesta inválida de Alpaki (${response.status}).`)
+  }
+
+  if (!response.ok) {
+    const message = data?.message || `HTTP ${response.status}`
+    throw new Error(`Alpaki respondió error: ${message}`)
+  }
+
+  return data
+}

package/lib/cli.js

@@ -0,0 +1,170 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fetchSkill, fetchSkillsCatalog, resolveSkillPath } from './api.js'
+import { printHelp, printSkillInstalled, printCatalog } from './print.js'
+import { resolveInstallDir } from './paths.js'
+
+/**
+ * @param {string[]} argv
+ */
+export async function runCli(argv) {
+  const args = parseArgs(argv)
+
+  if (args.help || (!args.skill && !args.list && !args.search)) {
+    printHelp()
+    if (!args.help && !args.skill && !args.list && !args.search) {
+      process.exitCode = 1
+    }
+    return
+  }
+
+  if (args.list || args.search) {
+    const catalog = await fetchSkillsCatalog({
+      search: args.search || '',
+      category: args.category || '',
+      page: args.page,
+      perPage: args.perPage,
+      apiBase: args.api,
+    })
+    printCatalog(catalog, { search: args.search || '' })
+    return
+  }
+
+  const skillPath = resolveSkillPath(args.skill)
+  const skill = await fetchSkill(skillPath, { apiBase: args.api })
+  const installRoot = resolveInstallDir({
+    cwd: process.cwd(),
+    target: args.dir,
+    global: args.global,
+    tool: args.tool,
+  })
+
+  const folderName = skill.slug || skillPath.slug
+  const skillDir = path.join(installRoot, folderName)
+  const skillFile = path.join(skillDir, 'SKILL.md')
+  const body = buildSkillMarkdown(skill)
+
+  await mkdir(skillDir, { recursive: true })
+  await writeFile(skillFile, body, 'utf8')
+
+  printSkillInstalled({
+    skill,
+    skillPath,
+    skillFile,
+    installRoot,
+  })
+}
+
+/**
+ * @param {string[]} argv
+ */
+function parseArgs(argv) {
+  /** @type {Record<string, any>} */
+  const out = {
+    help: false,
+    list: false,
+    global: false,
+    skill: '',
+    search: '',
+    category: '',
+    dir: '',
+    tool: 'cursor',
+    api: '',
+    page: 1,
+    perPage: 24,
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i]
+    const next = argv[i + 1]
+
+    if (token === '-h' || token === '--help') {
+      out.help = true
+      continue
+    }
+    if (token === 'list' || token === '--list') {
+      out.list = true
+      continue
+    }
+    if (token === 'search' || token === '--search') {
+      out.search = next || ''
+      i += 1
+      continue
+    }
+    if (token === '--skill' || token === '-s') {
+      out.skill = next || ''
+      i += 1
+      continue
+    }
+    if (token === '--dir' || token === '-d') {
+      out.dir = next || ''
+      i += 1
+      continue
+    }
+    if (token === '--tool' || token === '-t') {
+      out.tool = next || 'cursor'
+      i += 1
+      continue
+    }
+    if (token === '--api') {
+      out.api = next || ''
+      i += 1
+      continue
+    }
+    if (token === '--category' || token === '-c') {
+      out.category = next || ''
+      i += 1
+      continue
+    }
+    if (token === '--page') {
+      out.page = Number(next) || 1
+      i += 1
+      continue
+    }
+    if (token === '--per-page') {
+      out.perPage = Number(next) || 24
+      i += 1
+      continue
+    }
+    if (token === '--global' || token === '-g') {
+      out.global = true
+      continue
+    }
+    if (!token.startsWith('-') && !out.skill && token.includes('/')) {
+      out.skill = token
+      continue
+    }
+  }
+
+  return out
+}
+
+/**
+ * @param {{ title?: string, slug?: string, excerpt?: string, content?: string, sourceName?: string, category?: { name?: string, slug?: string } | null, license?: string }} skill
+ */
+function buildSkillMarkdown(skill) {
+  const name = skill.sourceName || skill.slug || skill.title || 'skill'
+  const description = (skill.excerpt || skill.title || name).replace(/\s+/g, ' ').trim()
+  const lines = [
+    '---',
+    `name: ${yamlQuote(name)}`,
+    `description: ${yamlQuote(description)}`,
+  ]
+
+  if (skill.license) {
+    lines.push(`license: ${yamlQuote(skill.license)}`)
+  }
+
+  lines.push('---', '')
+  lines.push((skill.content || '').trim(), '')
+
+  return `${lines.join('\n').trim()}\n`
+}
+
+/**
+ * @param {string} value
+ */
+function yamlQuote(value) {
+  const safe = String(value).replace(/"/g, '\\"')
+  return `"${safe}"`
+}

package/lib/paths.js

@@ -0,0 +1,23 @@
+import os from 'node:os'
+import path from 'node:path'
+
+/**
+ * @param {{ cwd: string, target?: string, global?: boolean, tool?: string }} options
+ */
+export function resolveInstallDir(options) {
+  if (options.target) {
+    return path.resolve(options.cwd, options.target)
+  }
+
+  const tool = String(options.tool || 'cursor').toLowerCase()
+  const relative =
+    tool === 'claude' || tool === 'claude-code'
+      ? path.join('.claude', 'skills')
+      : path.join('.cursor', 'skills')
+
+  if (options.global) {
+    return path.join(os.homedir(), relative)
+  }
+
+  return path.join(options.cwd, relative)
+}

package/lib/print.js

@@ -0,0 +1,78 @@
+export function printHelp() {
+  console.log(`
+alpaki-skills — instala skills de Alpaki en Cursor / Claude Code
+
+Uso:
+  npx alpaki-skills@latest --skill <categoria/slug>
+  npx alpaki-skills@latest creative-design/3d-web-experience
+  npx alpaki-skills@latest list
+  npx alpaki-skills@latest search "frontend"
+
+Opciones:
+  --skill, -s     Ruta categoria/slug (ej. development/api-design)
+  --dir, -d       Carpeta destino (default: ./.cursor/skills)
+  --tool, -t      cursor | claude   (default: cursor)
+  --global, -g    Instalar en el home del usuario
+  --api           Base URL de la API (default: https://api.alpaki.app)
+  --category, -c  Filtrar catálogo por categoría
+  --page          Página del catálogo
+  --per-page      Items por página
+  --help, -h      Mostrar ayuda
+
+Ejemplos:
+  npx alpaki-skills@latest --skill creative-design/3d-web-experience
+  npx alpaki-skills@latest --skill git/commit --tool claude
+  npx alpaki-skills@latest list --category development
+`)
+}
+
+/**
+ * @param {{ skill: any, skillPath: { path: string }, skillFile: string, installRoot: string }} payload
+ */
+export function printSkillInstalled(payload) {
+  const { skill, skillPath, skillFile, installRoot } = payload
+  console.log(`
+✓ Skill instalada
+
+  ${skill.title || skill.slug}
+  Origen: ${skillPath.path}
+  Destino: ${skillFile}
+  Carpeta: ${installRoot}
+
+Ábrela en Cursor como skill local o cópiala a tu flujo de agente.
+Catálogo: https://alpaki.app/skills
+`)
+}
+
+/**
+ * @param {{ items?: any[], total?: number, page?: number, totalPages?: number, categories?: any[] }} catalog
+ * @param {{ search?: string }} [meta]
+ */
+export function printCatalog(catalog, meta = {}) {
+  const items = catalog.items || []
+  const total = catalog.total ?? items.length
+  const header = meta.search ? `Resultados para "${meta.search}"` : 'Catálogo Alpaki Skills'
+
+  console.log(`\n${header} (${total})\n`)
+
+  if (!items.length) {
+    console.log('No hay skills con ese filtro.\n')
+    return
+  }
+
+  for (const item of items) {
+    const pathLabel = item.sourcePath || item.slug
+    const category = item.category?.name || 'Skill'
+    console.log(`- ${pathLabel}`)
+    console.log(`  ${item.title} · ${category}`)
+    if (item.excerpt) {
+      const excerpt = String(item.excerpt).replace(/\s+/g, ' ').slice(0, 110)
+      console.log(`  ${excerpt}${item.excerpt.length > 110 ? '…' : ''}`)
+    }
+    console.log('')
+  }
+
+  if ((catalog.totalPages || 1) > 1) {
+    console.log(`Página ${catalog.page || 1} de ${catalog.totalPages}. Usa --page para ver más.\n`)
+  }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "alpaki-skills",
+  "version": "1.0.0",
+  "description": "CLI para instalar skills de Alpaki en Cursor / Claude Code",
+  "type": "module",
+  "bin": {
+    "alpaki-skills": "bin/alpaki-skills.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node ./bin/alpaki-skills.js",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "alpaki",
+    "skills",
+    "cursor",
+    "claude",
+    "cli"
+  ],
+  "author": "Alpaki",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielandrehz/alpaki-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/danielandrehz/alpaki-skills/issues"
+  },
+  "homepage": "https://alpaki.app/skills"
+}