claude-code-arcane 1.0.0 → 1.1.0

package/skills/pgvector-search/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pgvector-search
+description: "Búsqueda semántica con Postgres + pgvector: embeddings, schema con columna vector, índices HNSW/IVFFlat, queries de similitud y RAG. Usar para implementar semantic search o retrieval sobre Postgres."
+category: "backend"
+argument-hint: "[setup|index|query|rag]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# pgvector-search — Búsqueda semántica con Postgres
+
+## MANDATORY WORKFLOW
+
+**Antes de generar o modificar código/schema, completar estos pasos en orden.**
+
+### Step 0: Gather Requirements
+1. **Modelo de embeddings** y dimensión (ej: OpenAI `text-embedding-3-small` = 1536; Cohere = 1024)
+2. **Volumen** de vectores (define el índice: HNSW para alta recall, IVFFlat para datasets grandes/escritura frecuente)
+3. **Métrica de distancia:** cosine (`<=>`, default para texto) / L2 (`<->`) / inner product (`<#>`)
+4. ¿Es para RAG (retrieval + LLM) o solo ranking de similitud?
+
+### Step 1: Habilitar extensión + schema
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE TABLE documents (
+  id bigserial PRIMARY KEY,
+  content text NOT NULL,
+  embedding vector(1536) NOT NULL,
+  metadata jsonb
+);
+```
+
+### Step 2: Índice
+```sql
+-- HNSW: mejor recall/latencia, recomendado por defecto
+CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);
+-- IVFFlat (alternativa para datasets muy grandes): definir lists ≈ rows/1000
+```
+
+### Step 3: Insertar embeddings
+Generar el embedding del `content` con el modelo y guardarlo. (Si usás Next + AI SDK, ver skill `ai-sdk-setup`.)
+```ts
+const { embedding } = await embed({ model, value: content });
+await sql`INSERT INTO documents (content, embedding) VALUES (${content}, ${JSON.stringify(embedding)})`;
+```
+
+### Step 4: Query de similitud
+```sql
+SELECT content, 1 - (embedding <=> $1) AS similarity
+FROM documents
+ORDER BY embedding <=> $1   -- usa el índice
+LIMIT 5;
+```
+
+### Step 5: Buenas prácticas
+- **Chunking** del contenido antes de embeddear (no documentos enteros)
+- Filtrar por `metadata` (jsonb) + similitud para hybrid search
+- `SET hnsw.ef_search` para tunear recall vs latencia
+- Re-embeddear si cambia el modelo (la dimensión debe matchear)
+- No mezclar embeddings de modelos distintos en la misma columna
+
+## Cierre
+
+Verificar que el índice se usa (`EXPLAIN ANALYZE` debe mostrar Index Scan, no Seq Scan) y medir recall/latencia con queries reales. Schema + índice + query validados → setup **READY**. Confirmar cambios de schema con el usuario antes de aplicarlos. Siguiente paso: skill `ai-sdk-setup` para generar embeddings, o `database-indexing` para tuning.
+
+---
+
+_Inspirado en `postgres-semantic-search` de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane. Relacionado: skill `database-indexing`._

package/skills/seo-nextjs/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: seo-nextjs
+description: "SEO técnico para Next.js App Router: Metadata API, generateMetadata dinámico, sitemap.ts, robots.ts, JSON-LD structured data, Open Graph y canonical. Usar al agregar o auditar SEO en una app Next."
+category: "frontend"
+argument-hint: "[metadata|sitemap|jsonld|audit]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# seo-nextjs — SEO técnico para Next.js
+
+## MANDATORY WORKFLOW
+
+**Antes de generar o modificar código, completar estos pasos en orden.**
+
+### Step 0: Determinar scope
+1. ¿App nueva o auditoría de SEO existente?
+2. ¿Contenido estático, dinámico (DB/CMS) o mixto?
+3. ¿Necesita structured data (JSON-LD) para rich results? (artículos, productos, FAQ, breadcrumbs)
+
+### Step 1: Metadata base (`app/layout.tsx`)
+```ts
+export const metadata: Metadata = {
+  metadataBase: new URL('https://example.com'),
+  title: { default: 'Site', template: '%s · Site' },
+  description: '...',
+  openGraph: { type: 'website', siteName: 'Site', images: ['/og.png'] },
+  twitter: { card: 'summary_large_image' },
+  alternates: { canonical: '/' },
+};
+```
+
+### Step 2: Metadata dinámica (`generateMetadata`)
+```ts
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const post = await getPost(params.slug);
+  return {
+    title: post.title,
+    description: post.excerpt,
+    alternates: { canonical: `/blog/${post.slug}` },
+    openGraph: { images: [post.cover] },
+  };
+}
+```
+Nunca tags `<meta>` manuales en el body — siempre la Metadata API.
+
+### Step 3: sitemap.ts y robots.ts
+```ts
+// app/sitemap.ts
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  const posts = await getAllPosts();
+  return [{ url: 'https://example.com', changeFrequency: 'daily' },
+    ...posts.map(p => ({ url: `https://example.com/blog/${p.slug}`, lastModified: p.updatedAt }))];
+}
+// app/robots.ts → reglas + link al sitemap
+```
+
+### Step 4: JSON-LD structured data
+```tsx
+<script type="application/ld+json"
+  dangerouslySetInnerHTML={{ __html: JSON.stringify({
+    '@context': 'https://schema.org', '@type': 'Article',
+    headline: post.title, datePublished: post.date, author: {...} }) }} />
+```
+Validar con Rich Results Test de Google.
+
+### Step 5: Checklist
+- [ ] `metadataBase` seteado (evita URLs OG rotas)
+- [ ] Canonical en cada page indexable
+- [ ] OG image 1200×630 por page importante
+- [ ] sitemap.ts + robots.ts presentes
+- [ ] JSON-LD donde aplique rich result
+- [ ] Sin `noindex` accidental en prod
+- [ ] LCP/CLS sanos (ver skill `nextjs-best-practices`)
+
+## Cierre
+
+Validar el structured data con el Rich Results Test de Google y los meta tags con el inspector del navegador. Si el checklist pasa → SEO **READY**. Confirmar cambios con el usuario antes de escribir. Siguiente paso: skill `nextjs-best-practices` para Web Vitals, o `ai-seo` para estrategia de contenido.
+
+---
+
+_Inspirado en las skills de SEO de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane. Relacionado: skill `ai-seo`._