@maccesar/aiskills 1.7.0

package/lib/symlink.js

@@ -0,0 +1,154 @@
+/**
+ * Cross-platform symlink utilities
+ * Creates symlinks with fallback to copy on Windows
+ */
+
+import { mkdirSync, existsSync } from 'fs';
+import { symlink, readlink, unlink, lstat } from 'fs/promises';
+import { join, dirname, relative } from 'path';
+import { copy, remove } from 'fs-extra';
+import { isWindows } from './platform.js';
+
+/**
+ * Create a symlink or copy as fallback
+ * @param {string} target - Target path (what the symlink points to)
+ * @param {string} path - Symlink path (where to create it)
+ * @param {boolean} useRelative - Whether to use a relative path for the symlink
+ * @returns {Promise<boolean>} True if successful
+ */
+export async function createSymlinkOrCopy(target, path, useRelative = false) {
+  // Ensure parent directory exists
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Remove existing file/directory/symlink
+  if (existsSync(path)) {
+    await removePath(path);
+  }
+
+  // Determine final target path
+  let finalTarget = target;
+  if (useRelative) {
+    finalTarget = relative(dirname(path), target);
+  }
+
+  // Try creating symlink first
+  try {
+    // Windows requires 'junction' or 'dir' for directory symlinks
+    await symlink(finalTarget, path, 'dir');
+    return true;
+  } catch (error) {
+    // On Windows or if symlink fails, copy the directory
+    if (isWindows() || error.code === 'EPERM' || error.code === 'EXDEV') {
+      try {
+        await copy(target, path, { overwrite: true });
+        return true;
+      } catch (copyError) {
+        console.error(`Failed to copy: ${copyError.message}`);
+        return false;
+      }
+    }
+    console.error(`Failed to create symlink: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Remove a file, directory, or symlink
+ * @param {string} path - Path to remove
+ * @returns {Promise<void>}
+ */
+async function removePath(path) {
+  try {
+    await remove(path);
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Create symlinks for all skills to a platform directory
+ * @param {string} platformSkillsDir - Platform skills directory
+ * @param {Array} skills - List of skill names
+ * @param {string} baseDir - Optional base directory for target resolution
+ * @returns {Promise<Object>} Results object with success/failure counts
+ */
+export async function createSkillSymlinks(platformSkillsDir, skills, baseDir) {
+  const { getAgentsSkillsDir } = await import('./config.js');
+  const agentsSkillsDir = getAgentsSkillsDir(baseDir);
+
+  const results = {
+    linked: [],
+    failed: [],
+  };
+
+  // Ensure platform directory exists
+  if (!existsSync(platformSkillsDir)) {
+    mkdirSync(platformSkillsDir, { recursive: true });
+  }
+
+  // Use relative symlinks if we are in a local installation
+  const useRelative = !!baseDir;
+
+  for (const skill of skills) {
+    const target = join(agentsSkillsDir, skill);
+    const linkPath = join(platformSkillsDir, skill);
+
+    if (await createSymlinkOrCopy(target, linkPath, useRelative)) {
+      results.linked.push(skill);
+    } else {
+      results.failed.push(skill);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Check if a path is a symlink
+ * @param {string} path - Path to check
+ * @returns {Promise<boolean>} True if symlink
+ */
+export async function isSymlink(path) {
+  try {
+    const { lstat } = await import('fs/promises');
+    const stats = await lstat(path);
+    return stats.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve symlink target
+ * @param {string} path - Symlink path
+ * @returns {Promise<string|null>} Target path or null
+ */
+export async function resolveSymlink(path) {
+  try {
+    return await readlink(path);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove a symlink and recreate it (update)
+ * @param {string} target - New target path
+ * @param {string} path - Symlink path
+ * @returns {Promise<boolean>} True if successful
+ */
+export async function updateSymlink(target, path) {
+  await removePath(path);
+  return createSymlinkOrCopy(target, path);
+}
+
+export default {
+  createSymlinkOrCopy,
+  createSkillSymlinks,
+  isSymlink,
+  resolveSymlink,
+  updateSymlink,
+};

package/lib/utils.js

@@ -0,0 +1,49 @@
+/**
+ * Utility functions
+ */
+
+/**
+ * Format a list of items for display
+ * @param {Array} items - Array of strings
+ * @returns {string} Comma-separated list
+ */
+export function formatList(items) {
+  return items.join(', ');
+}
+
+/**
+ * Parse version string to compare
+ * @param {string} version - Version string (e.g., "1.0.0")
+ * @returns {Array} Array of version parts
+ */
+export function parseVersion(version) {
+  const matches = version.match(/\d+/g) || [];
+  return matches.map((v) => parseInt(v, 10));
+}
+
+/**
+ * Compare two version strings
+ * @param {string} v1 - First version
+ * @param {string} v2 - Second version
+ * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
+ */
+export function compareVersions(v1, v2) {
+  const parts1 = parseVersion(v1);
+  const parts2 = parseVersion(v2);
+
+  for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
+    const p1 = parts1[i] || 0;
+    const p2 = parts2[i] || 0;
+
+    if (p1 < p2) return -1;
+    if (p1 > p2) return 1;
+  }
+
+  return 0;
+}
+
+export default {
+  formatList,
+  parseVersion,
+  compareVersions,
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@maccesar/aiskills",
+  "version": "1.7.0",
+  "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
+  "type": "module",
+  "bin": {
+    "aiskills": "./bin/aiskills.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "lint": "eslint lib/**/*.js",
+    "format": "prettier --write lib/**/*.js"
+  },
+  "keywords": [
+    "ai",
+    "skills",
+    "claude",
+    "claude-code",
+    "gemini",
+    "codex",
+    "llm",
+    "agents",
+    "refactoring-ui",
+    "design",
+    "ui",
+    "ux"
+  ],
+  "author": "César Estrada <maccesar@gmail.com> (https://github.com/macCesar)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/macCesar/aiskills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/macCesar/aiskills/issues"
+  },
+  "homepage": "https://github.com/macCesar/aiskills#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "fs-extra": "^11.3.3",
+    "ora": "^9.1.0",
+    "tar": "^7.5.7"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/humaniza/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: humaniza
+description: Humaniza textos en español (especialmente es-MX) eliminando patrones típicos de IA y devolviendo una versión natural y clara. Úsalo al editar emails, documentación,  marketing, soporte o textos técnicos en español cuando el usuario pida "humanizar", "hacerlo más natural", "quitar tono IA" o "hacerlo sonar humano".
+allowed-tools: Read, Write, Edit, Grep, Glob, AskUserQuestion
+---
+
+# Humaniza
+
+Editor de estilo para español de México. El objetivo es quitar tics de IA sin cambiar el contenido.
+
+## Alcance
+
+- Mantener significado, datos y estructura general.
+- Respetar puntuación y signos de apertura/cierre.
+- Conservar registro (tú/usted) salvo solicitud explícita.
+- Preferir es-MX: evitar "vosotros", "ordenador", "móvil", "coche" cuando el texto sea neutro.
+- No inventar fuentes ni datos.
+
+## Flujo
+
+1. Detectar tono y audiencia a partir del texto.
+2. Si el usuario pide un modo (marketing, técnico, soporte, etc.), priorizarlo.
+3. Identificar tics de IA con `references/ai-patterns-es.md` y `references/lexicon-es-mx.md`.
+4. Reescribir: cortar relleno, concretar, variar ritmo, usar "ser/estar" cuando sea más claro.
+5. Ajustar el tono según `references/modes-es-mx.md` si aplica.
+6. Añadir voz humana cuando aplique con `references/voice-es-mx.md`.
+7. Pasar QA final con `references/checklist.md`.
+
+## Modos (si el usuario lo pide)
+
+- Marketing persuasivo
+- Técnico
+- Soporte
+- Emails
+- Documentación
+- Posts/ensayo
+
+Reglas completas: `references/modes-es-mx.md`.
+
+## Reglas de edición
+
+- Evitar frases infladas y lenguaje promocional si el texto no es marketing.
+- Reducir conectores repetidos y muletillas ("además", "en este sentido", "cabe destacar").
+- Eliminar secciones plantilla si no aportan datos.
+- Mantener términos técnicos, marcas, API, código y nombres propios.
+- Dividir párrafos largos cuando sea necesario para claridad.
+
+## Salida
+
+- Devolver solo el texto final, sin explicación, a menos que el usuario la pida.
+- Si hiciste una suposición importante (tono o público), agrega una línea breve para confirmarla.

package/skills/humaniza/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Humaniza"
+  short_description: "Humaniza textos en español (es-MX) y elimina tics de IA"
+  default_prompt: "Humaniza este texto en español (es-MX), manteniendo el significado y el tono. Devuelve solo el texto final."

package/skills/humaniza/references/ai-patterns-es.md

@@ -0,0 +1,51 @@
+# Patrones de IA (ES)
+
+Usa esta lista para detectar tics comunes y reescribirlos.
+
+## 1. Énfasis exagerado de importancia
+Antes: La actualización marca un hito en la evolución de la plataforma.
+Después: La actualización mejora la plataforma con cambios concretos.
+
+## 2. Notabilidad o cobertura sin fuente
+Antes: Ha sido destacado por diversos medios y expertos del sector.
+Después: Elimina la frase si no hay fuente o dato verificable.
+
+## 3. Gerundios y participios de relleno
+Antes: El servicio permite pagos rápidos, facilitando la experiencia del usuario.
+Después: El servicio permite pagos rápidos y simplifica la experiencia.
+
+## 4. Lenguaje promocional fuera de contexto
+Antes: Una solución innovadora y de clase mundial para tu empresa.
+Después: Una solución para gestionar X de forma más simple.
+
+## 5. Atribuciones vagas
+Antes: Expertos señalan que el mercado crecerá pronto.
+Después: Elimina la atribución si no hay fuente concreta.
+
+## 6. Secciones plantilla ("Retos y futuro")
+Antes: Retos y futuro: Aún hay desafíos por delante, pero el panorama es prometedor.
+Después: Incluye solo retos concretos con datos, o elimina la sección.
+
+## 7. Conectores sobreusados
+Antes: Además..., Además..., Además...
+Después: Combina oraciones y elimina conectores innecesarios.
+
+## 8. Evasión de ser/estar
+Antes: La app se erige como la opción ideal para equipos remotos.
+Después: La app es una opción para equipos remotos.
+
+## 9. Paralelismos negativos
+Antes: No solo mejora el rendimiento, sino que también optimiza la memoria.
+Después: Mejora el rendimiento y optimiza la memoria.
+
+## 10. Regla de tres forzada
+Antes: Es rápida, segura y confiable.
+Después: Es rápida y confiable.
+
+## 11. Calcos del inglés
+Antes: Eventualmente lanzaremos la actualización.
+Después: Finalmente lanzaremos la actualización.
+
+## 12. Cierres vacíos
+Antes: En conclusión, este avance es clave para el futuro.
+Después: Este avance reduce el tiempo de carga.

package/skills/humaniza/references/checklist.md

@@ -0,0 +1,9 @@
+# Checklist final
+
+- El significado se mantuvo intacto.
+- No se inventaron datos ni fuentes.
+- Se redujeron muletillas y conectores repetidos.
+- El ritmo es natural y variado.
+- Se mantuvo el registro (tú/usted) y el tono.
+- La puntuación y los párrafos son claros.
+- El vocabulario es consistente con es-MX.

package/skills/humaniza/references/examples.md

@@ -0,0 +1,17 @@
+# Ejemplos rápidos
+
+## Técnico
+Antes: Esta funcionalidad se erige como un pilar fundamental, ofreciendo un rendimiento sobresaliente.
+Después: Esta funcionalidad es clave y mejora el rendimiento.
+
+## Email
+Antes: Agradecemos su valiosa colaboración, la cual resulta esencial para el éxito de esta iniciativa.
+Después: Gracias por tu apoyo. Es importante para que esto funcione.
+
+## Soporte
+Antes: Le informamos que su solicitud ha sido procesada exitosamente y en breve recibirá una actualización.
+Después: Tu solicitud ya se procesó. En breve recibirás una actualización.
+
+## Marketing
+Antes: Una experiencia única e inolvidable que transforma la manera en que trabajas.
+Después: Una experiencia pensada para que trabajes más rápido y con menos fricción.

package/skills/humaniza/references/lexicon-es-mx.md

@@ -0,0 +1,36 @@
+# Léxico de tics comunes (ES-MX)
+
+Usa estas listas para detectar patrones repetitivos o inflados. No elimines todo: solo reduce lo que suena mecánico o sobra.
+
+## Conectores sobreusados (modera la repetición)
+además, asimismo, sin embargo, no obstante, por otro lado, por ende, en este sentido, a su vez, cabe destacar, en el marco de, de hecho, en definitiva, en conclusión, por lo tanto, por consiguiente, en consecuencia.
+
+## Frases infladas
+marca un hito, punto de inflexión, de vital importancia, se posiciona como, representa un cambio, refleja el compromiso, pone en valor, en el corazón de, panorama en constante evolución.
+
+## Adjetivos promocionales vacíos
+vibrante, impresionante, fascinante, revolucionario, innovador, de clase mundial, de vanguardia, único, incomparable, sobresaliente, notable, extraordinario.
+
+## Evasión de ser/estar
+se erige como, se configura como, constituye, representa, supone, se traduce en, viene a ser, resulta ser.
+
+## Atribuciones vagas
+según expertos, diversos estudios, algunos analistas, observadores señalan, se cree, está comprobado (sin fuente).
+
+## Calcos y anglicismos frecuentes
+- eventualmente -> finalmente / con el tiempo
+- aplicar a (trabajo) -> postularse a
+- soportar (apoyo) -> apoyar
+- impactar (afectar) -> afectar
+- realizar una decisión -> tomar una decisión
+- en base a -> con base en / basado en
+- a nivel de -> en / respecto a (si no son niveles reales)
+- en términos de -> respecto a / sobre
+
+## Preferencias es-MX (si el texto es neutro)
+ordenador -> computadora
+móvil -> celular
+fichero -> archivo
+vosotros -> ustedes
+coche -> auto o carro
+conducir -> manejar

package/skills/humaniza/references/modes-es-mx.md

@@ -0,0 +1,41 @@
+# Modos y reglas (ES-MX)
+
+Si el usuario pide un modo, aplicar estas reglas. Si no pide modo, usar estilo general.
+
+## Marketing persuasivo
+
+- Enfatizar beneficios concretos y resultados.
+- Mantener el CTA claro si existe; si no existe, no inventarlo.
+- Evitar promesas absolutas o grandilocuencia sin sustento.
+- Frases más cortas y ritmo dinámico.
+
+## Técnico
+
+- Precisión sobre estilo: sin metáforas ni adornos.
+- Mantener términos técnicos, nombres de APIs y convenciones.
+- Preferir verbos directos y oraciones simples.
+- Si hay pasos o listas, mantener el orden y la claridad.
+
+## Soporte
+
+- Tono empático y directo, sin culpar al usuario.
+- Confirmar el problema y ofrecer pasos claros.
+- Evitar tecnicismos innecesarios.
+
+## Emails
+
+- Mantener saludo y cierre si existen.
+- Ajustar formalidad según el registro (tú/usted).
+- Quitar relleno y llegar al punto.
+
+## Documentación
+
+- Tono neutral y consistente.
+- Preferir instrucciones en imperativo cuando aplique.
+- Evitar marketing y opiniones.
+
+## Posts / ensayo
+
+- Mantener voz personal si existe.
+- Permitir preguntas retóricas moderadas.
+- Cuidar ritmo y transiciones, sin inflar el mensaje.

package/skills/humaniza/references/voice-es-mx.md

@@ -0,0 +1,24 @@
+# Voz y naturalidad (ES-MX)
+
+## Ritmo
+- Alterna oraciones cortas y medianas. Evita la cadencia monótona.
+- Corta frases largas con puntos cuando el texto se vuelve denso.
+
+## Voz humana
+- Si el texto lo permite, incluye una opinión ligera o una duda real.
+- Evita sonar enciclopédico cuando el objetivo es comunicar.
+- No agregues opiniones en textos técnicos o legales.
+
+## Concreción
+- Prefiere verbos directos ("usa", "permite", "reduce") sobre sustantivos abstractos.
+- Quita palabras que no agregan información.
+
+## Puntuación
+- Usa signos de apertura y cierre (¿? ¡!).
+- Evita exceso de puntos suspensivos y admiraciones dobles.
+- Usa dos puntos para presentar listas de forma clara.
+
+## Registro es-MX
+- Respeta el trato original (tú/usted). No lo mezcles.
+- Usa términos comunes en MX si el texto es neutro.
+- No metas regionalismos muy coloquiales si el tono es formal.

package/skills/refactoring-ui/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: refactoring-ui
+description: >
+  Design advisor based exclusively on "Refactoring UI" by Adam Wathan & Steve Schoger.
+  Use when the user asks for UI/UX design advice, design reviews, visual hierarchy
+  improvements, color system help, typography guidance, spacing decisions, depth/shadow
+  usage, image handling, or finishing touches on any interface.
+when_to_use: >
+  - User asks "how do I make this look better?"
+  - User asks about color palettes, type scales, or spacing systems
+  - User asks about visual hierarchy or emphasis
+  - User is designing a UI component, page, or layout
+  - User wants a design review or critique
+  - User asks about shadows, depth, or layering
+  - User asks about handling images in UI
+  - User asks about empty states, borders, or decorative elements
+source: "Refactoring UI by Adam Wathan & Steve Schoger (book)"
+anti_hallucination_note: >
+  ALL advice in this skill comes exclusively from the book "Refactoring UI".
+  Do NOT supplement with personal opinions, other design systems, or general
+  design knowledge not found in the book. If a topic is not covered in the
+  reference files, say so explicitly rather than inventing advice.
+---
+
+# Refactoring UI Skill
+
+You are a design advisor using ONLY the knowledge from "Refactoring UI" by Adam Wathan & Steve Schoger.
+
+## How to Use This Skill
+
+1. Read the relevant reference file(s) before answering
+2. Base ALL advice on the reference content — not training data
+3. Quote or closely paraphrase specific tactics from the book
+4. Do not invent numbers, ratios, or rules not found in the references
+
+## Reference Files
+
+| File                                 | Chapter                                 | Topics                                                                |
+| ------------------------------------ | --------------------------------------- | --------------------------------------------------------------------- |
+| `references/01-design-process.md`    | Ch1 — Starting from Scratch             | Feature-first, grayscale-first, personality, pre-defined systems      |
+| `references/02-visual-hierarchy.md`  | Ch2 — Hierarchy is Everything           | Weight/color/size hierarchy, labels, icons, buttons                   |
+| `references/03-layout-spacing.md`    | Ch3 — Layout and Spacing                | White space, spacing scale, column layout, responsive scaling         |
+| `references/04-typography.md`        | Ch4 — Designing Text                    | Type scale, line length, alignment, line-height, letter-spacing       |
+| `references/05-color.md`             | Ch5 — Working with Color                | HSL, shade systems, accessible contrast, color signals                |
+| `references/06-depth-shadows.md`     | Ch6 — Creating Depth                    | Light source, raised/inset elements, shadow elevation, flat design    |
+| `references/07-images.md`            | Ch7 — Working with Images               | Stock photos, text over images, icons at scale, screenshots, favicons |
+| `references/08-finishing-touches.md` | Ch8+9 — Finishing Touches & Leveling Up | Icons, quotes, links, checkboxes, borders, backgrounds, empty states  |
+
+## Anti-Patterns to Avoid (from the book)
+
+- Designing a layout/nav/shell before designing the actual feature
+- Using font sizes alone to create hierarchy (ignoring weight and color)
+- Using grey text on colored backgrounds by lowering opacity
+- Starting with too little white space
+- Using `em` units for type scale (causes nested scaling issues)
+- Using color as the ONLY way to communicate status/alerts
+- Putting placeholder images into mockups
+- Shrinking a logo to use as favicon
+- Using `lighten()`/`darken()` preprocessor functions to generate shades

package/skills/refactoring-ui/references/01-design-process.md

@@ -0,0 +1,72 @@
+# Ch1 — Starting from Scratch
+
+Source: "Refactoring UI" by Adam Wathan & Steve Schoger
+
+---
+
+## Feature-First Design
+
+- Design actual features, not shells, navbars, or layouts first
+- Pick one real feature and design it end-to-end before thinking about navigation
+- The shell and layout emerge naturally from the features — don't force it first
+- Resist the urge to design "the app" — design what people will actually use
+
+## Low-Fidelity First (Thick Sharpie Trick)
+
+- Start with low-fidelity mockups — details don't matter at this stage
+- Use a thick Sharpie (or similar): makes it physically impossible to add fine details
+- Sketch ideas, not pixels — get the general layout and content blocks right
+- Avoid wireframing tools that tempt you into making polished designs too early
+- Don't move to high-fidelity until the concept is locked
+
+## Work in Cycles, Be a Pessimist
+
+- Only design what you're ready to build right now
+- Work in short design-then-build cycles, not one giant design phase
+- Be a pessimist: cut features before building, not after
+- A simple, complete experience beats a complex, half-built one
+- Add features to the next version; ship the core first
+
+## Choose a Personality
+
+Design decisions that define personality:
+
+**Font choice:**
+- Serif → classic, elegant, literary (e.g., law firms, newspapers)
+- Rounded sans-serif → playful, friendly, approachable
+- Neutral sans-serif → plain, professional, clean
+
+**Color:**
+- Blue → safe, familiar, trustworthy
+- Gold/yellow → luxurious, sophisticated
+- Pink → fun, not-too-serious
+
+**Border radius:**
+- Small or none → formal, serious
+- Large → playful, friendly
+
+**Language register:**
+- "An error occurred" → formal
+- "Uh oh, something broke!" → casual and approachable
+
+Every choice should reinforce the same personality — be consistent.
+
+## Pre-Define Systems Before Designing
+
+Define your system up front; make decisions once instead of every time:
+
+- **Font sizes:** 8-10 values (type scale)
+- **Font weights:** usually 2 (normal 400, bold 600/700)
+- **Colors:** 8-10 shades per color, plus primary, greys, accents
+- **Spacing:** 10-15 values on a non-linear scale
+- **Box shadows:** 5 options (small, medium, large, extra-large, inner)
+- **Border radius:** 3-5 options (none, small, medium, large, full)
+- **Border widths:** 2-3 options
+
+**Benefit:** When you need to make a decision, you're choosing from a small set, not from infinity. Eliminates decision fatigue.
+
+## Process of Elimination
+
+- Don't try to "find the perfect value" — start from a set and eliminate
+- Too big? Try the next smaller option. Too close to white? Try the next shade darker.
+- Systems make design systematic, not artistic guesswork