Skill Builder

Turn the user's plain-language request into a complete, production-ready agent skill saved to the local skills directory.

Goal

Given a user description like "crea una skill che compone il mio CV markdown in PDF" or "a skill that lints my dockerfiles", produce a working skill the agent can load on demand.

Output

Write to ~/.agents/skills/<name>/SKILL.md (plus optional supporting files in the same folder). The name is derived from the description: lowercase, kebab-case, concise.

Structure of a Good Skill

A skill is a SKILL.md file with YAML frontmatter, plus optional companion files (scripts, references, templates) in the same directory.

1. Frontmatter (required): name and description. The description must be specific enough that the agent can auto-trigger the skill later. Include concrete trigger phrases the user would say. Keep it under ~15 lines.
2. Body: Markdown with clear sections:
   • # <Name> — human title.
   • ## When to Use — exact trigger conditions.
   • ## Workflow / steps — numbered, concrete, actionable.
   • Rules, gotchas, examples, verification steps.
   • Note any relative helper files (scripts/, references/).

Scaffolding Rules

• Match the user's language (if they speak Italian, write the skill body in Italian unless they ask otherwise). Keep name and description in English for registry compatibility.
• Reuse the user's existing conventions: read a sibling skill's SKILL.md first to mirror structure (frontmatter style, heading levels, tone).
• If the task needs code, put it in a scripts/ subfolder and reference it relatively.
• Prefer the simplest working version (YAGNI). Add only what the task actually needs.
• Do NOT add fabricated flags, dependencies, or tools the user didn't mention. If unsure, ask one clarifying question before writing.

Procedure

1. Read the user's request. Identify: goal, domain, input, output, trigger phrases.
2. Ask ONE clarifying question only if a decision materially changes the skill (language? scope? strictness? output location?). Otherwise proceed.
3. Derive name from the description.
4. Write ~/.agents/skills/<name>/SKILL.md with frontmatter + body.
5. If supporting scripts/templates are needed, write them under the same folder.
6. Verify: confirm the file path and a one-line summary of what the skill does. Confirm it will be auto-discovered (it lives in ~/.agents/skills/).

Example Frontmatter

---
name: cv-to-pdf
description: >
  Composes the user's markdown CV into a styled PDF. Use when the user says
  "componi il mio cv in pdf", "create a PDF resume", "export my cv to pdf".
---

Quality Checks

• name is present and kebab-case.
• description contains trigger phrases and says when to use the skill.
• Body is actionable (numbered steps) and self-contained.
• No secrets/absolute private paths hard-coded unless the user asked.
• Language matches the user's request.