README.md

---
title: Skill Forge
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
---

# 🛠️ 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.