Construimos un redactor con IA usando Claude — esto aprendimos sobre prompt engineering

El primer prompt que le mandamos a Claude para generar un post fue una sola frase: "escribe un post sobre WebMCP, tono profesional, 1500 palabras". Lo que volvió fue una redacción de instituto sobre transformación digital con cinco emojis y dos "sinergias". Borramos todo y volvimos a empezar.

Lo que aprendimos en las semanas siguientes no fue sobre prompts. Fue sobre arquitectura. Estos son los cuatro patrones que hicieron pasar al redactor de "regular" a "publicable sin tocar nada".

1. Las skills son ficheros markdown — no strings dentro del código

El primer instinto fue meter el prompt en una constante de TypeScript. Funcionó dos días. Cuando quisimos cambiar el tono del blog para un autor concreto, había que abrir el código, modificar la constante, hacer commit, redeploy. Ridículo para un cambio que es texto plano.

La solución es trivial pero potente: cada "skill" es un fichero markdown.

skills/
├── blog-writer.md
├── linkedin-writer.md
├── x-writer.md
└── brand-reviewer.md

El runtime los carga como texto, los inyecta en el system prompt, y cada uno describe en lenguaje natural cómo debe comportarse el modelo: tono, estructura, longitud, qué hacer y qué evitar.

Las instrucciones son datos, no código. Cambiar el comportamiento del redactor para un blog cualquiera no requiere un deploy — requiere editar un markdown.

2. JSON Schema en la salida, siempre

Pedirle a un LLM "devuelve un objeto con título, subtítulo y cuerpo" sin más, te garantiza que el 5% de las generaciones vienen mal formadas. Markdown donde esperabas HTML, comillas curvas en una clave, un bloque de código que se cuela en el título.

La API de Claude tiene una herramienta concreta para esto: tool use con input_schema. Defines un JSON Schema y el modelo se compromete a respetarlo.

const tools = [{
  name: "publish_post",
  description: "Generate a complete blog post ready to publish.",
  input_schema: {
    type: "object",
    properties: {
      title:            { type: "string", maxLength: 70 },
      subtitle:         { type: "string", maxLength: 150 },
      meta_description: { type: "string", maxLength: 160 },
      slug:             { type: "string", pattern: "^[a-z0-9-]+$" },
      body_html:        { type: "string" },
      tags:             { type: "array", items: { type: "string" }, maxItems: 5 },
    },
    required: ["title", "subtitle", "body_html", "slug", "tags"],
  },
}];

Con esto, las salidas mal formadas pasaron del 5% a literalmente cero en semanas de uso. maxLength en el título no es solo una constraint del SEO — es una pista al modelo de que el output va a ser parseado y no debe extenderse "porque sí".

3. Separar tono de forma

El error más sutil al principio: meter en el mismo prompt el tono ("habla como un ingeniero senior") y la forma ("estructura con H2 y bullets"). El modelo prioriza una y descuida la otra de forma impredecible.

El patrón que funciona es separarlas en dos capas distintas del system prompt:

1. Capa BRAND: tono, vocabulario prohibido, voz del autor. Cargada desde BRAND.md del blog.
2. Capa SKILL: forma del output, longitud, estructura HTML. Cargada desde skills/blog-writer.md.

El user message contiene solo el tema. Los dos sistemas se quedan estables, el tema rota cada generación. Con esta separación, una generación que sale "bien escrita pero descabellada" se debugea en BRAND. Una "razonable pero mal estructurada" se debugea en SKILL. No tienes que adivinar qué frase del prompt mover.

4. Defensive parsing por defecto

Aun con tool use forzado, una de cada cien generaciones llega rara — el modelo decide responder en texto plano porque interpretó mal la conversación, o el endpoint devuelve un 529 transitorio. Si tu código asume que la respuesta siempre tiene la forma esperada, vas a tener un crash en producción cuando menos te conviene.

Cada acceso a la respuesta pasa por un nullish coalescing:

const post = response?.content?.[0]?.input;
const title = post?.title ?? "Untitled draft";
const body = post?.body_html ?? "<p>Generation failed. Try again.</p>";

No es paranoia — es trato realista con un sistema probabilístico. Programa para el 99% feliz pero captura el 1% sin elegancia.

El resultado, en números

Con estos cuatro patrones, el redactor genera posts en menos de 30 segundos, con HTML válido, schema.org listo para incrustar, slug correcto, y meta description ajustada al límite exacto de Google. La tasa de "publicable sin tocar nada" pasó del 30% inicial al 85% actual. El 15% restante son retoques cosméticos del autor — porque la voz, al final, sigue siendo suya.

El secreto, otra vez, no es el prompt. Es la arquitectura alrededor del prompt: skills modulares, JSON Schema estricto, capas separadas, parsing defensivo. Lo que llamamos "prompt engineering" es 20% prompt y 80% sistema.

---

Las skills que usamos están en github.com/agentikas/agentikas-skills, con licencia permisiva. El runtime que las carga es @agentikas/ai, parte del monorepo. Fork, copia, mejora.