Skill Forge: static browser app + Python/MCP port for Agent Skills

LICENSE

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

README.md

@@ -1,10 +1,65 @@
 ---
 title: Skill Forge
-emoji: 😻
-colorFrom: blue
+emoji: 🛠️
+colorFrom: indigo
 colorTo: purple
 sdk: static
+app_file: index.html
 pinned: false
+license: mit
+short_description: Validate, lint & scaffold Agent Skills in-browser
+tags:
+- agents
+- skills
+- developer-tools
+- mcp
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🛠️ Skill Forge
+
+Author better **Agent Skills**. A `SKILL.md` is a YAML frontmatter block plus a
+Markdown body; the `description` is how an agent decides *when* to use the skill,
+and a weak one means it silently never fires. Skill Forge catches that before you
+ship — and runs **entirely client-side**, so nothing you paste leaves the page.
+
+Rides the current wave of skill-centric agents — e.g.
+[*Repo-To-Skill: Distilling GitHub Repositories Into AI4AI Skills*](https://huggingface.co/papers/2609.02749)
+(a 5,000-skill library lifting an ML-research agent +134% on MLE-bench) — by
+making the authoring loop fast and checkable.
+
+## What it does
+
+| Tab | Use |
+|---|---|
+| **Validate** | Parse `SKILL.md`; flag broken frontmatter, non-kebab `name`, over-long or trigger-less `description`, empty/unstructured body, absolute bundled-file links. |
+| **Lint description** | Score the `description` 0–100 for trigger reliability: length band, explicit "use when", action verbs, concrete examples, third-person phrasing. |
+| **Scaffold** | Generate a valid starter `SKILL.md` from a name + description + trigger, then validate it. |
+
+## Files
+
+| File | |
+|---|---|
+| [`index.html`](index.html) + [`skillforge.js`](skillforge.js) | the static app (js-yaml from CDN) |
+| [`skillforge.py`](skillforge.py) | same logic in Python — `validate_skill`, `lint_description`, `scaffold_skill`, `package_skill` |
+| [`app.py`](app.py) | Gradio UI **+ MCP server** (`skill_validate`, `skill_lint_description`, `skill_scaffold`) for running locally / on a PRO Space |
+| `test_skillforge.py`, `test_skillforge.mjs` | self-checks for both ports |
+
+### Run the MCP server locally
+
+```bash
+pip install -r requirements.txt
+python app.py        # UI on :7860, MCP at /gradio_api/mcp/sse
+```
+
+```json
+{ "mcpServers": { "skill-forge": { "url": "http://localhost:7860/gradio_api/mcp/sse" } } }
+```
+
+## Scope
+
+Only the **stable, host-agnostic** structure of the format is enforced — no
+host-specific frontmatter keys are required, and unknown keys are reported as
+info, not errors. The linter is opinionated about `description` quality because
+that is what determines whether the skill is ever used.
+
+MIT licensed. All original code.

app.py

@@ -0,0 +1,124 @@
+"""
+Skill Forge — a Gradio app + MCP server for authoring Agent Skills.
+
+Tabs: validate a SKILL.md, score its `description` for trigger reliability, and
+scaffold a new skill. The same three functions are exposed as MCP tools
+(`skill_validate`, `skill_lint_description`, `skill_scaffold`) so an agent can
+call them while it writes skills for itself.
+
+Run locally:  python app.py   (UI on :7860, MCP at /gradio_api/mcp/sse)
+"""
+
+import gradio as gr
+
+from skillforge import validate_skill, lint_description, scaffold_skill, package_skill
+
+EXAMPLE = """---
+name: changelog-writer
+description: Drafts a release changelog from merged PRs. Use when the user asks to \
+"write the changelog", "summarize what shipped", or prep release notes for a tag.
+---
+
+# Changelog Writer
+
+## When to use this skill
+- The user is cutting a release and wants notes grouped by type.
+
+## Instructions
+1. Collect merged PRs since the last tag.
+2. Group as Features / Fixes / Internal and write one line each.
+"""
+
+
+def skill_validate(skill_md: str) -> str:
+    """Validate a SKILL.md against the Agent Skill format.
+
+    Args:
+        skill_md: Full text of a SKILL.md file (YAML frontmatter + Markdown body).
+
+    Returns:
+        A Markdown report listing errors, warnings, and info.
+    """
+    return validate_skill(skill_md).as_markdown()
+
+
+def skill_lint_description(description: str) -> str:
+    """Score a skill `description` for how reliably an agent will trigger on it.
+
+    Args:
+        description: The frontmatter `description` string on its own.
+
+    Returns:
+        A Markdown report ending with 'Trigger score: N/100'.
+    """
+    return lint_description(description).as_markdown()
+
+
+def skill_scaffold(name: str, description: str, when_to_use: str = "") -> str:
+    """Generate a ready-to-edit SKILL.md for a new Agent Skill.
+
+    Args:
+        name: kebab-case skill name, e.g. 'pdf-form-filler'.
+        description: What the skill does and when to use it.
+        when_to_use: Optional extra trigger examples.
+
+    Returns:
+        The full text of a SKILL.md file.
+    """
+    return scaffold_skill(name, description, when_to_use)
+
+
+def _package(skill_md: str):
+    data = package_skill(skill_md)
+    path = "skill.zip"
+    with open(path, "wb") as f:
+        f.write(data)
+    return path
+
+
+with gr.Blocks(title="Skill Forge") as demo:
+    gr.Markdown(
+        "# 🛠️ Skill Forge\n"
+        "Validate, lint, and scaffold **Agent Skills** (`SKILL.md`). "
+        "Also an MCP server — point your agent at `/gradio_api/mcp/sse`."
+    )
+
+    with gr.Tab("Validate"):
+        md_in = gr.Code(value=EXAMPLE, language="yaml", label="SKILL.md", lines=20)
+        with gr.Row():
+            v_btn = gr.Button("Validate", variant="primary")
+            z_btn = gr.Button("Package as .zip")
+        v_out = gr.Markdown()
+        z_out = gr.File(label="Packaged skill", visible=True)
+        v_btn.click(skill_validate, md_in, v_out, api_name="skill_validate")
+        z_btn.click(_package, md_in, z_out)
+
+    with gr.Tab("Lint description"):
+        d_in = gr.Textbox(
+            label="Frontmatter `description`", lines=4,
+            value=('Drafts a release changelog from merged PRs. Use when the user '
+                   'asks to "write the changelog" or prep release notes.'))
+        d_btn = gr.Button("Score it", variant="primary")
+        d_out = gr.Markdown()
+        d_btn.click(skill_lint_description, d_in, d_out,
+                    api_name="skill_lint_description")
+
+    with gr.Tab("Scaffold"):
+        s_name = gr.Textbox(label="name (kebab-case)", value="terraform-plan-reviewer")
+        s_desc = gr.Textbox(label="description", lines=3,
+                            value="Reviews a Terraform plan and summarizes drift and risk.")
+        s_when = gr.Textbox(label="when to use (optional)",
+                            value='the user runs "terraform plan" and wants a risk summary')
+        s_btn = gr.Button("Generate SKILL.md", variant="primary")
+        s_out = gr.Code(language="yaml", label="SKILL.md")
+        s_btn.click(skill_scaffold, [s_name, s_desc, s_when], s_out,
+                    api_name="skill_scaffold")
+
+    gr.Markdown(
+        "---\nRules checked: frontmatter parses as YAML · `name` kebab-case ≤64 · "
+        "`description` present ≤1024 with a trigger cue · non-empty structured body · "
+        "relative bundled-file links. MIT licensed."
+    )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

index.html

@@ -1,19 +1,180 @@
-<!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Skill Forge</title>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/js-yaml/4.1.0/js-yaml.min.js"></script>
+<style>
+  :root {
+    --bg: #fbfbfd; --fg: #1a1a22; --muted: #6b7280; --card: #fff;
+    --border: #e5e7eb; --accent: #5b4bd6; --code: #f4f4f7;
+    --err: #b91c1c; --warn: #b45309; --info: #1d4ed8; --ok: #047857;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0f0f14; --fg: #e6e6ec; --muted: #9ca3af; --card: #17171f;
+      --border: #2a2a35; --accent: #a99bff; --code: #1e1e28;
+      --err: #f87171; --warn: #fbbf24; --info: #93c5fd; --ok: #6ee7b7;
+    }
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; background: var(--bg); color: var(--fg);
+    font: 15px/1.55 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  }
+  .wrap { max-width: 900px; margin: 0 auto; padding: 32px 20px 64px; }
+  h1 { font-size: 26px; margin: 0 0 4px; }
+  .sub { color: var(--muted); margin: 0 0 24px; }
+  .sub code { background: var(--code); padding: 1px 6px; border-radius: 5px; }
+  .tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--border); margin-bottom: 20px; flex-wrap: wrap; }
+  .tabs button {
+    background: none; border: 0; padding: 10px 14px; font: inherit; color: var(--muted);
+    cursor: pointer; border-bottom: 2px solid transparent; margin-bottom: -1px;
+  }
+  .tabs button.active { color: var(--fg); border-bottom-color: var(--accent); font-weight: 600; }
+  .panel { display: none; }
+  .panel.active { display: block; }
+  label { display: block; font-weight: 600; margin: 14px 0 6px; font-size: 13px; }
+  textarea, input[type=text] {
+    width: 100%; background: var(--card); color: var(--fg); border: 1px solid var(--border);
+    border-radius: 8px; padding: 10px 12px; font: inherit; resize: vertical;
+  }
+  textarea.mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; }
+  button.go {
+    margin-top: 14px; background: var(--accent); color: #fff; border: 0; border-radius: 8px;
+    padding: 10px 18px; font: inherit; font-weight: 600; cursor: pointer;
+  }
+  button.go.ghost { background: transparent; color: var(--accent); border: 1px solid var(--accent); margin-left: 8px; }
+  .out {
+    margin-top: 18px; background: var(--card); border: 1px solid var(--border);
+    border-radius: 10px; padding: 4px 18px; min-height: 40px;
+  }
+  .out:empty { display: none; }
+  .out h2 { font-size: 17px; }
+  .out ul { padding-left: 20px; }
+  .out li { margin: 3px 0; }
+  .out code, pre code { background: var(--code); padding: 1px 5px; border-radius: 4px; font-size: 13px; }
+  pre { background: var(--code); padding: 14px; border-radius: 8px; overflow-x: auto; }
+  .foot { margin-top: 40px; color: var(--muted); font-size: 13px; border-top: 1px solid var(--border); padding-top: 16px; }
+  .foot a { color: var(--accent); }
+  .badge { display:inline-block; font-size:12px; padding:2px 8px; border-radius:999px; border:1px solid var(--border); color:var(--muted); }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>🛠️ Skill Forge</h1>
+  <p class="sub">
+    Validate, lint &amp; scaffold <strong>Agent Skills</strong> (<code>SKILL.md</code>).
+    Runs entirely in your browser. <span class="badge">static · no upload</span>
+  </p>
+
+  <div class="tabs">
+    <button data-tab="validate" class="active">Validate</button>
+    <button data-tab="lint">Lint description</button>
+    <button data-tab="scaffold">Scaffold</button>
+  </div>
+
+  <section id="validate" class="panel active">
+    <label for="md">SKILL.md</label>
+    <textarea id="md" class="mono" rows="18"></textarea>
+    <button class="go" id="v-go">Validate</button>
+    <button class="go ghost" id="v-sample">Load a broken sample</button>
+    <div class="out" id="v-out"></div>
+  </section>
+
+  <section id="lint" class="panel">
+    <label for="desc">Frontmatter <code>description</code></label>
+    <textarea id="desc" rows="4">Drafts a release changelog from merged PRs. Use when the user asks to "write the changelog" or prep release notes for a tag.</textarea>
+    <button class="go" id="l-go">Score it</button>
+    <div class="out" id="l-out"></div>
+  </section>
+
+  <section id="scaffold" class="panel">
+    <label for="s-name">name (kebab-case)</label>
+    <input type="text" id="s-name" value="terraform-plan-reviewer" />
+    <label for="s-desc">description</label>
+    <textarea id="s-desc" rows="3">Reviews a Terraform plan and summarizes drift and risk.</textarea>
+    <label for="s-when">when to use (optional)</label>
+    <input type="text" id="s-when" value='the user runs "terraform plan" and wants a risk summary' />
+    <button class="go" id="s-go">Generate SKILL.md</button>
+    <div class="out" id="s-out"></div>
+  </section>
+
+  <p class="foot">
+    Checks the stable, host-agnostic structure: frontmatter parses as YAML ·
+    <code>name</code> kebab-case ≤64 · <code>description</code> present ≤1024 with a
+    trigger cue · non-empty structured body · relative bundled-file links. Unknown
+    frontmatter keys are info, not errors.
+    <br />Need the MCP server / Python API? <code>pip install -r requirements.txt &amp;&amp; python app.py</code>
+    — see <a href="./app.py">app.py</a>. MIT licensed · all original code.
+  </p>
+</div>
+
+<script src="./skillforge.js"></script>
+<script>
+(function () {
+  var GOOD = "---\nname: changelog-writer\ndescription: Drafts a release changelog from merged PRs. Use when the user asks to \"write the changelog\", \"summarize what shipped\", or prep release notes for a tag.\n---\n\n# Changelog Writer\n\n## When to use this skill\n- The user is cutting a release and wants notes grouped by type.\n\n## Instructions\n1. Collect merged PRs since the last tag.\n2. Group as Features / Fixes / Internal and write one line each.\n";
+  var BROKEN = "---\nname: Changelog_Writer!!\ndescription: makes changelogs\n---\n";
+
+  document.getElementById("md").value = GOOD;
+
+  // tiny markdown renderer: headings (##), bold (**x**), inline `code`, - lists
+  function mdToHtml(md) {
+    var lines = md.split("\n"), html = [], inList = false;
+    lines.forEach(function (ln) {
+      var h = ln.match(/^(#{1,6})\s+(.*)/);
+      if (h) { if (inList) { html.push("</ul>"); inList = false; }
+        html.push("<h" + h[1].length + ">" + inline(h[2]) + "</h" + h[1].length + ">"); return; }
+      var li = ln.match(/^-\s+(.*)/);
+      if (li) { if (!inList) { html.push("<ul>"); inList = true; }
+        html.push("<li>" + inline(li[1]) + "</li>"); return; }
+      if (inList) { html.push("</ul>"); inList = false; }
+      if (ln.trim() === "") return;
+      html.push("<p>" + inline(ln) + "</p>");
+    });
+    if (inList) html.push("</ul>");
+    return html.join("\n");
+  }
+  function esc(s) { return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;"); }
+  function inline(s) {
+    return esc(s).replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>")
+                 .replace(/`([^`]+)`/g, "<code>$1</code>");
+  }
+
+  document.querySelectorAll(".tabs button").forEach(function (b) {
+    b.addEventListener("click", function () {
+      document.querySelectorAll(".tabs button").forEach(function (x) { x.classList.remove("active"); });
+      document.querySelectorAll(".panel").forEach(function (x) { x.classList.remove("active"); });
+      b.classList.add("active");
+      document.getElementById(b.dataset.tab).classList.add("active");
+    });
+  });
+
+  document.getElementById("v-go").addEventListener("click", function () {
+    document.getElementById("v-out").innerHTML =
+      mdToHtml(SkillForge.validateSkill(document.getElementById("md").value).asMarkdown());
+  });
+  document.getElementById("v-sample").addEventListener("click", function () {
+    document.getElementById("md").value = BROKEN;
+    document.getElementById("v-go").click();
+  });
+  document.getElementById("l-go").addEventListener("click", function () {
+    document.getElementById("l-out").innerHTML =
+      mdToHtml(SkillForge.lintDescription(document.getElementById("desc").value).asMarkdown());
+  });
+  document.getElementById("s-go").addEventListener("click", function () {
+    var md = SkillForge.scaffoldSkill(
+      document.getElementById("s-name").value,
+      document.getElementById("s-desc").value,
+      document.getElementById("s-when").value);
+    var rep = SkillForge.validateSkill(md);
+    document.getElementById("s-out").innerHTML =
+      "<pre><code>" + esc(md) + "</code></pre>" + mdToHtml(rep.asMarkdown());
+  });
+
+  document.getElementById("v-go").click();
+})();
+</script>
+</body>
 </html>

requirements.txt

@@ -0,0 +1,2 @@
+gradio[mcp]>=5.9
+PyYAML>=6

skillforge.js

@@ -0,0 +1,186 @@
+/*
+ * Skill Forge — browser port of skillforge.py.
+ * Pure functions; depends only on window.jsyaml (js-yaml UMD).
+ * Kept deliberately in lockstep with the Python module so behaviour matches.
+ */
+(function (global) {
+  "use strict";
+
+  const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+  const NAME_MAX = 64;
+  const DESC_MAX = 1024;
+  const KNOWN_KEYS = new Set([
+    "name", "description", "license", "allowed-tools", "allowed_tools",
+    "metadata", "version", "compatible-with", "compatible_with",
+  ]);
+  const TRIGGER_CUES = ["use when", "use this", "when the user", "when asked",
+    "trigger", "for tasks", "helps with", "invoke when"];
+
+  function Report() {
+    this.ok = true; this.errors = []; this.warnings = []; this.info = [];
+  }
+  Report.prototype.err = function (m) { this.errors.push(m); this.ok = false; };
+  Report.prototype.warn = function (m) { this.warnings.push(m); };
+  Report.prototype.note = function (m) { this.info.push(m); };
+  Report.prototype.asMarkdown = function () {
+    const head = this.ok ? "## ✅ Valid skill" : "## ❌ Invalid skill";
+    const out = [head, ""];
+    [["Errors", this.errors, "🔴"],
+     ["Warnings", this.warnings, "🟡"],
+     ["Info", this.info, "🔵"]].forEach(function (t) {
+      if (t[1].length) {
+        out.push("**" + t[0] + "**");
+        t[1].forEach(function (x) { out.push("- " + t[2] + " " + x); });
+        out.push("");
+      }
+    });
+    if (this.ok && !this.warnings.length) out.push("_No issues found._");
+    return out.join("\n").trim();
+  };
+
+  function splitFrontmatter(text) {
+    text = text.replace(/^/, "");
+    if (!text.startsWith("---")) return [null, text];
+    const m = text.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/);
+    if (!m) return [null, text];
+    return [m[1], m[2]];
+  }
+
+  function validateSkill(skillMd) {
+    const r = new Report();
+    if (!skillMd || !skillMd.trim()) { r.err("File is empty."); return r; }
+
+    const parts = splitFrontmatter(skillMd);
+    const fmRaw = parts[0], body = parts[1];
+    if (fmRaw === null) {
+      r.err("No YAML frontmatter. SKILL.md must start with a '---' fenced block.");
+      return r;
+    }
+    let fm;
+    try { fm = global.jsyaml.load(fmRaw) || {}; }
+    catch (e) { r.err("Frontmatter is not valid YAML: " + e.message); return r; }
+    if (typeof fm !== "object" || Array.isArray(fm)) {
+      r.err("Frontmatter must be a YAML mapping (key: value pairs)."); return r;
+    }
+
+    let name = fm.name;
+    if (name === undefined || name === null || !String(name).trim()) {
+      r.err("`name` is required in frontmatter.");
+    } else {
+      name = String(name).trim();
+      if (name.length > NAME_MAX) r.err("`name` is " + name.length + " chars; keep it <= " + NAME_MAX + ".");
+      if (!NAME_RE.test(name)) r.err("`name` must be kebab-case: lowercase letters, digits, single hyphens.");
+    }
+
+    let desc = fm.description;
+    if (desc === undefined || desc === null || !String(desc).trim()) {
+      r.err("`description` is required — it is how an agent decides to use the skill.");
+    } else {
+      desc = String(desc).trim();
+      if (desc.length > DESC_MAX) r.err("`description` is " + desc.length + " chars; keep it <= " + DESC_MAX + ".");
+      if (desc.length < 40) r.warn("`description` is very short; say what the skill does *and* when to use it.");
+      const low = desc.toLowerCase();
+      if (!TRIGGER_CUES.some(function (c) { return low.indexOf(c) !== -1; }))
+        r.warn("`description` has no explicit trigger ('Use when...'); agents may not fire it.");
+    }
+
+    if (!body.trim()) {
+      r.err("Body is empty. Put the actual instructions after the frontmatter.");
+    } else {
+      if (!/^#{1,6}\s/m.test(body) && body.length > 400)
+        r.warn("Long body with no Markdown headings; add structure for skimmability.");
+      const links = body.match(/\[[^\]]*\]\(([^)]+)\)/g) || [];
+      links.forEach(function (raw) {
+        const link = raw.match(/\(([^)]+)\)/)[1];
+        if (/^(https?:\/\/|#|mailto:)/.test(link)) return;
+        if (link.startsWith("/"))
+          r.warn("Absolute path link '" + link + "'; use a path relative to the skill folder.");
+      });
+    }
+
+    const unknown = Object.keys(fm).filter(function (k) { return !KNOWN_KEYS.has(k); }).sort();
+    if (unknown.length)
+      r.note("Non-standard frontmatter keys (ignored by most hosts): " + unknown.join(", "));
+
+    const at = fm["allowed-tools"] !== undefined ? fm["allowed-tools"] : fm.allowed_tools;
+    if (at !== undefined && at !== null && !Array.isArray(at) && typeof at !== "string")
+      r.warn("`allowed-tools` should be a list (or comma string) of tool names.");
+
+    return r;
+  }
+
+  function lintDescription(description) {
+    const r = new Report();
+    const d = (description || "").trim();
+    if (!d) { r.err("Empty description."); return r; }
+
+    let score = 100;
+    const low = d.toLowerCase();
+    const n = d.length;
+
+    if (n < 40) { score -= 35; r.warn("Too short (" + n + " chars). Aim for ~150–500."); }
+    else if (n < 150) { score -= 10; r.warn("A bit short (" + n + " chars); add concrete trigger cases."); }
+    else if (n > DESC_MAX) { score -= 30; r.err("Over the " + DESC_MAX + "-char limit (" + n + ")."); }
+    else if (n > 700) { score -= 8; r.warn("Long (" + n + " chars); tighten to the essentials."); }
+
+    if (!TRIGGER_CUES.some(function (c) { return low.indexOf(c) !== -1; })) {
+      score -= 25;
+      r.warn("No explicit trigger phrase. Add 'Use when the user...' with real examples.");
+    }
+    if (/^(this skill|a skill|the skill|this is)/.test(low)) {
+      score -= 10;
+      r.warn("Starts with 'This skill...'. Lead with the capability or the trigger.");
+    }
+    if (/\b(i|you|we|my|your)\b/.test(low)) {
+      score -= 6;
+      r.note("Uses first/second person; third-person reads better in a registry.");
+    }
+    const verbs = low.match(/\b(create|build|convert|review|audit|generate|analy[sz]e|extract|summari[sz]e|refactor|debug|validate|lint|format|deploy|test|search|fetch|translate|render|plan)\w*/g);
+    if (!verbs) { score -= 12; r.warn("No action verbs; name what the skill *does*."); }
+
+    if (/(e\.g\.|for example|such as|like )/.test(low)) r.note("Has examples — good for trigger matching.");
+    else { score -= 8; r.warn("No examples. Concrete phrases ('e.g. \"redesign my landing page\"') help matching."); }
+
+    score = Math.max(0, Math.min(100, score));
+    const verdict = score >= 80 ? "strong" : score >= 55 ? "usable" : "weak";
+    r.note("Trigger score: " + score + "/100 (" + verdict + ")");
+    r.ok = score >= 55;
+    r.score = score;
+    return r;
+  }
+
+  function scaffoldSkill(name, description, whenToUse) {
+    name = (name || "my-skill").trim().toLowerCase().replace(/ /g, "-").replace(/[^a-z0-9-]/g, "") || "my-skill";
+    let desc = (description || "").split(/\s+/).filter(Boolean).join(" ");
+    whenToUse = (whenToUse || "").trim();
+    if (whenToUse) {
+      if (desc.toLowerCase().indexOf("use when") === -1) {
+        desc = desc
+          ? desc + " Use when " + whenToUse.charAt(0).toLowerCase() + whenToUse.slice(1)
+          : "Use when " + whenToUse;
+      } else {
+        desc = desc + " " + whenToUse;
+      }
+    }
+    if (!desc) {
+      desc = 'Describe what this skill does and the concrete situations that should ' +
+             'trigger it, e.g. "Use when the user asks to ...".';
+    }
+    const title = name.replace(/-/g, " ").replace(/\b\w/g, function (c) { return c.toUpperCase(); });
+    return "---\n" +
+      "name: " + name + "\n" +
+      "description: " + desc + "\n" +
+      "---\n\n" +
+      "# " + title + "\n\n" +
+      "## When to use this skill\n\n" +
+      "- Trigger 1 — a concrete user request this handles.\n" +
+      "- Trigger 2 — another phrasing or situation.\n" +
+      "- Do **not** use it for: <the near-miss cases that belong elsewhere>.\n\n" +
+      "## Instructions\n\n" +
+      "1. First step.\n2. Second step.\n3. What to hand back to the user.\n\n" +
+      "## Notes\n\n" +
+      "- Edge cases, gotchas, and links to bundled files (paths relative to this folder).\n";
+  }
+
+  global.SkillForge = { splitFrontmatter, validateSkill, lintDescription, scaffoldSkill };
+})(typeof window !== "undefined" ? window : globalThis);

skillforge.py

@@ -0,0 +1,295 @@
+"""
+Skill Forge — core logic for validating, linting, and scaffolding Agent Skills.
+
+An "Agent Skill" is a folder with a SKILL.md at its root: a YAML frontmatter
+block (`--- ... ---`) followed by a Markdown body. The frontmatter names the
+skill and, crucially, describes *when* an agent should reach for it; the body is
+the instructions the agent follows once it does.
+
+This module is pure stdlib + PyYAML so it can be unit-tested without Gradio.
+Nothing here is copied from any spec document — the rules below are the stable,
+widely-agreed structural constraints of the format.
+"""
+
+from __future__ import annotations
+
+import io
+import re
+import zipfile
+from dataclasses import dataclass, field
+
+import yaml
+
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+NAME_MAX = 64
+DESC_MAX = 1024
+# Keys commonly recognised across skill hosts. Unknown keys are only *info*.
+KNOWN_KEYS = {
+    "name", "description", "license", "allowed-tools", "allowed_tools",
+    "metadata", "version", "compatible-with", "compatible_with",
+}
+TRIGGER_CUES = ("use when", "use this", "when the user", "when asked",
+                "trigger", "for tasks", "helps with", "invoke when")
+
+
+@dataclass
+class Report:
+    ok: bool = True
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    info: list[str] = field(default_factory=list)
+
+    def err(self, m: str) -> None:
+        self.errors.append(m)
+        self.ok = False
+
+    def warn(self, m: str) -> None:
+        self.warnings.append(m)
+
+    def note(self, m: str) -> None:
+        self.info.append(m)
+
+    def as_markdown(self) -> str:
+        head = "## ✅ Valid skill" if self.ok else "## ❌ Invalid skill"
+        lines = [head, ""]
+        for label, items, icon in (
+            ("Errors", self.errors, "🔴"),
+            ("Warnings", self.warnings, "🟡"),
+            ("Info", self.info, "🔵"),
+        ):
+            if items:
+                lines.append(f"**{label}**")
+                lines += [f"- {icon} {x}" for x in items]
+                lines.append("")
+        if self.ok and not self.warnings:
+            lines.append("_No issues found._")
+        return "\n".join(lines).strip()
+
+
+def split_frontmatter(text: str) -> tuple[str | None, str]:
+    """Return (frontmatter_yaml, body). frontmatter is None if no leading block."""
+    text = text.lstrip("")
+    if not text.startswith("---"):
+        return None, text
+    m = re.match(r"^---[ \t]*\r?\n(.*?)\r?\n---[ \t]*\r?\n?(.*)\Z", text, re.S)
+    if not m:
+        return None, text
+    return m.group(1), m.group(2)
+
+
+def validate_skill(skill_md: str) -> Report:
+    """Validate a SKILL.md string against the Agent Skill format.
+
+    Args:
+        skill_md: Full text of a SKILL.md file (frontmatter + Markdown body).
+
+    Returns:
+        A Report with ok/errors/warnings/info. Errors mean the skill will not
+        load or trigger reliably; warnings are quality problems worth fixing.
+    """
+    r = Report()
+    if not skill_md or not skill_md.strip():
+        r.err("File is empty.")
+        return r
+
+    fm_raw, body = split_frontmatter(skill_md)
+    if fm_raw is None:
+        r.err("No YAML frontmatter. SKILL.md must start with a '---' fenced block.")
+        return r
+
+    try:
+        fm = yaml.safe_load(fm_raw) or {}
+    except yaml.YAMLError as e:
+        r.err(f"Frontmatter is not valid YAML: {e}")
+        return r
+    if not isinstance(fm, dict):
+        r.err("Frontmatter must be a YAML mapping (key: value pairs).")
+        return r
+
+    # name
+    name = fm.get("name")
+    if not name or not str(name).strip():
+        r.err("`name` is required in frontmatter.")
+    else:
+        name = str(name).strip()
+        if len(name) > NAME_MAX:
+            r.err(f"`name` is {len(name)} chars; keep it <= {NAME_MAX}.")
+        if not NAME_RE.match(name):
+            r.err("`name` must be kebab-case: lowercase letters, digits, single hyphens.")
+
+    # description
+    desc = fm.get("description")
+    if not desc or not str(desc).strip():
+        r.err("`description` is required — it is how an agent decides to use the skill.")
+    else:
+        desc = str(desc).strip()
+        if len(desc) > DESC_MAX:
+            r.err(f"`description` is {len(desc)} chars; keep it <= {DESC_MAX}.")
+        if len(desc) < 40:
+            r.warn("`description` is very short; say what the skill does *and* when to use it.")
+        if not any(cue in desc.lower() for cue in TRIGGER_CUES):
+            r.warn("`description` has no explicit trigger ('Use when...'); agents may not fire it.")
+
+    # body
+    if not body.strip():
+        r.err("Body is empty. Put the actual instructions after the frontmatter.")
+    else:
+        if not re.search(r"^#{1,6}\s", body, re.M) and len(body) > 400:
+            r.warn("Long body with no Markdown headings; add structure for skimmability.")
+        for link in re.findall(r"\[[^\]]*\]\(([^)]+)\)", body):
+            if link.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            if link.startswith("/"):
+                r.warn(f"Absolute path link '{link}'; use a path relative to the skill folder.")
+
+    # unknown keys (informational only)
+    unknown = sorted(set(fm) - KNOWN_KEYS)
+    if unknown:
+        r.note(f"Non-standard frontmatter keys (ignored by most hosts): {', '.join(unknown)}")
+
+    at = fm.get("allowed-tools", fm.get("allowed_tools"))
+    if at is not None and not isinstance(at, (list, str)):
+        r.warn("`allowed-tools` should be a list (or comma string) of tool names.")
+
+    return r
+
+
+def lint_description(description: str) -> Report:
+    """Score a skill `description` for how reliably an agent will trigger on it.
+
+    Args:
+        description: The frontmatter `description` string.
+
+    Returns:
+        A Report whose first info line is 'Trigger score: N/100'.
+    """
+    r = Report()
+    d = (description or "").strip()
+    if not d:
+        r.err("Empty description.")
+        return r
+
+    score = 100
+    low = d.lower()
+
+    n = len(d)
+    if n < 40:
+        score -= 35
+        r.warn(f"Too short ({n} chars). Aim for ~150–500.")
+    elif n < 150:
+        score -= 10
+        r.warn(f"A bit short ({n} chars); add concrete trigger cases.")
+    elif n > DESC_MAX:
+        score -= 30
+        r.err(f"Over the {DESC_MAX}-char limit ({n}).")
+    elif n > 700:
+        score -= 8
+        r.warn(f"Long ({n} chars); tighten to the essentials.")
+
+    if not any(cue in low for cue in TRIGGER_CUES):
+        score -= 25
+        r.warn("No explicit trigger phrase. Add 'Use when the user...' with real examples.")
+
+    if low.startswith(("this skill", "a skill", "the skill", "this is")):
+        score -= 10
+        r.warn("Starts with 'This skill...'. Lead with the capability or the trigger.")
+
+    if re.search(r"\b(i|you|we|my|your)\b", low):
+        score -= 6
+        r.note("Uses first/second person; third-person reads better in a registry.")
+
+    verbs = re.findall(r"\b(create|build|convert|review|audit|generate|analy[sz]e|"
+                       r"extract|summari[sz]e|refactor|debug|validate|lint|format|"
+                       r"deploy|test|search|fetch|translate|render|plan)\w*", low)
+    if not verbs:
+        score -= 12
+        r.warn("No action verbs; name what the skill *does*.")
+
+    if "e.g." in low or "for example" in low or "such as" in low or "like " in low:
+        r.note("Has examples — good for trigger matching.")
+    else:
+        score -= 8
+        r.warn("No examples. Concrete phrases ('e.g. \"redesign my landing page\"') help matching.")
+
+    score = max(0, min(100, score))
+    verdict = "strong" if score >= 80 else "usable" if score >= 55 else "weak"
+    r.note(f"Trigger score: {score}/100 ({verdict})")
+    r.ok = score >= 55
+    return r
+
+
+def scaffold_skill(name: str, description: str, when_to_use: str = "") -> str:
+    """Return a ready-to-edit SKILL.md for a new Agent Skill.
+
+    Args:
+        name: kebab-case skill name, e.g. 'pdf-form-filler'.
+        description: One or two sentences: what it does and when to use it.
+        when_to_use: Optional extra trigger examples appended to the description.
+
+    Returns:
+        The full text of a SKILL.md file.
+    """
+    name = (name or "my-skill").strip().lower().replace(" ", "-")
+    name = re.sub(r"[^a-z0-9-]", "", name) or "my-skill"
+    desc = " ".join((description or "").split())
+    if when_to_use.strip():
+        extra = when_to_use.strip()
+        if "use when" not in desc.lower():
+            desc = f"{desc} Use when {extra[0].lower()}{extra[1:]}" if desc else f"Use when {extra}"
+        else:
+            desc = f"{desc} {extra}"
+    if not desc:
+        desc = ("Describe what this skill does and the concrete situations that "
+                "should trigger it, e.g. \"Use when the user asks to ...\".")
+
+    return f"""---
+name: {name}
+description: {desc}
+---
+
+# {name.replace('-', ' ').title()}
+
+## When to use this skill
+
+- Trigger 1 — a concrete user request this handles.
+- Trigger 2 — another phrasing or situation.
+- Do **not** use it for: <the near-miss cases that belong elsewhere>.
+
+## Instructions
+
+1. First step.
+2. Second step.
+3. What to hand back to the user.
+
+## Notes
+
+- Edge cases, gotchas, and links to bundled files (paths relative to this folder).
+"""
+
+
+def package_skill(skill_md: str, extra_files: dict[str, str] | None = None) -> bytes:
+    """Zip a SKILL.md (and optional sibling files) into a distributable archive.
+
+    Args:
+        skill_md: The SKILL.md text. Must validate without errors.
+        extra_files: Optional {relative_path: text_content} placed next to SKILL.md.
+
+    Returns:
+        Bytes of a .zip. Raises ValueError if the skill has validation errors.
+    """
+    rep = validate_skill(skill_md)
+    if not rep.ok:
+        raise ValueError("Skill has errors; fix them before packaging:\n" +
+                         "\n".join(rep.errors))
+    fm_raw, _ = split_frontmatter(skill_md)
+    name = str((yaml.safe_load(fm_raw) or {}).get("name", "skill")).strip()
+
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr(f"{name}/SKILL.md", skill_md)
+        for rel, content in (extra_files or {}).items():
+            rel = rel.lstrip("/")
+            if ".." in rel.split("/"):
+                raise ValueError(f"Unsafe path: {rel}")
+            z.writestr(f"{name}/{rel}", content)
+    return buf.getvalue()

test_skillforge.mjs

@@ -0,0 +1,62 @@
+/* Node smoke test for skillforge.js parity. Run: node test_skillforge.mjs
+ * Uses a minimal yaml shim covering only the shapes the tests exercise. */
+import { readFileSync } from "node:fs";
+import assert from "node:assert";
+import vm from "node:vm";
+
+const shim = {
+  load(src) {
+    const o = {};
+    for (const raw of src.split("\n")) {
+      const line = raw.replace(/\r$/, "");
+      if (!line.trim() || line.trim().startsWith("#")) continue;
+      const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+      if (!m) { const e = new Error("bad yaml line: " + line); throw e; }
+      let v = m[2].trim();
+      if (v.startsWith("[") && !v.endsWith("]")) throw new Error("unterminated flow seq");
+      o[m[1]] = v.replace(/^["']|["']$/g, "");
+    }
+    return o;
+  },
+};
+
+const ctx = { window: { jsyaml: shim }, globalThis: {} };
+vm.createContext(ctx);
+vm.runInContext(readFileSync(new URL("./skillforge.js", import.meta.url), "utf8"), ctx);
+const SF = ctx.window.SkillForge;
+
+const GOOD = `---
+name: pdf-form-filler
+description: Fills interactive PDF forms from a data mapping. Use when the user asks to complete or auto-fill a PDF form, e.g. "fill out this application PDF".
+---
+
+# PDF Form Filler
+
+## When to use
+- Fillable PDF + field values.
+
+## Instructions
+1. Inspect fields.
+2. Map and flatten.
+`;
+
+assert.ok(SF.validateSkill(GOOD).ok, "good skill should pass");
+assert.ok(!SF.validateSkill("# no frontmatter").ok, "missing frontmatter fails");
+
+const bad = SF.validateSkill('---\nname: Not_Kebab!!\ndescription: short\n---\n\nbody\n');
+assert.ok(!bad.ok && bad.errors.some(e => e.includes("kebab-case")), "kebab error");
+
+assert.ok(!SF.validateSkill('---\nname: [unclosed\n---\nbody\n').ok, "invalid yaml fails");
+
+const weak = SF.lintDescription("Does stuff.");
+const strong = SF.lintDescription(
+  'Converts Markdown notes into a styled slide deck. Use when the user asks to ' +
+  '"turn this into slides" or "make a deck", e.g. a report rendered as shareable slides.');
+assert.ok(weak.score < 55 && strong.score >= 55, `scores ${weak.score}/${strong.score}`);
+
+const md = SF.scaffoldSkill("My Cool Skill", "Reviews Terraform plans for drift.",
+  "the user runs terraform plan and wants a risk summary");
+assert.ok(md.includes("name: my-cool-skill"), "scaffold name");
+assert.ok(SF.validateSkill(md).ok, "scaffold output validates");
+
+console.log("all checks passed");

test_skillforge.py

@@ -0,0 +1,108 @@
+"""Self-check for skillforge.py.  Run: python test_skillforge.py"""
+import io
+import zipfile
+
+from skillforge import (validate_skill, lint_description, scaffold_skill,
+                        package_skill, split_frontmatter)
+
+GOOD = """---
+name: pdf-form-filler
+description: >
+  Fills interactive PDF forms from a data mapping and flattens the result.
+  Use when the user asks to complete, populate, or auto-fill a PDF form,
+  e.g. "fill out this application PDF" or "populate the tax form fields".
+license: MIT
+allowed-tools:
+  - Read
+  - Bash
+---
+
+# PDF Form Filler
+
+## When to use this skill
+- The user hands over a fillable PDF and field values.
+
+## Instructions
+1. Inspect the form fields.
+2. Map data onto them and flatten.
+"""
+
+
+def test_split():
+    fm, body = split_frontmatter(GOOD)
+    assert fm and "pdf-form-filler" in fm
+    assert body.strip().startswith("# PDF Form Filler")
+    assert split_frontmatter("no frontmatter here")[0] is None
+    # BOM + CRLF tolerance
+    assert split_frontmatter("---\r\nname: x\r\n---\r\nbody")[0].strip() == "name: x"
+
+
+def test_good_skill_passes():
+    r = validate_skill(GOOD)
+    assert r.ok, r.errors
+    assert not r.errors
+
+
+def test_missing_frontmatter():
+    r = validate_skill("# just a heading\n\nsome text")
+    assert not r.ok and any("frontmatter" in e for e in r.errors)
+
+
+def test_bad_name_and_desc():
+    md = "---\nname: Not_KebabCase!!\ndescription: short\n---\n\nbody text here\n"
+    r = validate_skill(md)
+    assert not r.ok
+    assert any("kebab-case" in e for e in r.errors)
+    assert any("short" in w for w in r.warnings)
+
+
+def test_empty_body():
+    md = "---\nname: ok-name\ndescription: " + "x" * 60 + " use when needed\n---\n\n   \n"
+    r = validate_skill(md)
+    assert not r.ok and any("Body is empty" in e for e in r.errors)
+
+
+def test_invalid_yaml():
+    r = validate_skill("---\nname: [unclosed\n---\nbody\n")
+    assert not r.ok and any("YAML" in e for e in r.errors)
+
+
+def test_lint_scores():
+    weak = lint_description("Does stuff.")
+    strong = lint_description(
+        "Converts Markdown notes into a styled slide deck. Use when the user asks "
+        "to 'turn this into slides', 'make a deck', or 'present this document', "
+        "e.g. a report they want rendered as shareable slides.")
+    ws = int(weak.info[-1].split(":")[1].split("/")[0])
+    ss = int(strong.info[-1].split(":")[1].split("/")[0])
+    assert ws < 55 <= ss, (ws, ss)
+    assert strong.ok and not weak.ok
+
+
+def test_scaffold_roundtrips():
+    md = scaffold_skill("My Cool Skill",
+                        "Reviews Terraform plans for drift.",
+                        "the user runs terraform plan and wants a risk summary")
+    assert "name: my-cool-skill" in md
+    r = validate_skill(md)
+    assert r.ok, r.errors
+
+
+def test_package_rejects_bad_and_zips_good():
+    try:
+        package_skill("---\nname: X\n---\n")
+        assert False, "should have raised"
+    except ValueError:
+        pass
+    blob = package_skill(GOOD, {"reference.md": "# notes"})
+    with zipfile.ZipFile(io.BytesIO(blob)) as z:
+        names = z.namelist()
+    assert "pdf-form-filler/SKILL.md" in names
+    assert "pdf-form-filler/reference.md" in names
+
+
+if __name__ == "__main__":
+    for fn in list(globals().values()):
+        if callable(fn) and getattr(fn, "__name__", "").startswith("test_"):
+            fn()
+    print("all checks passed")