Initial public release of Skillforge

Author: Bobtoshi

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm test
+      - run: npm run build

.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+.DS_Store
+*.log

LICENSE

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

@@ -0,0 +1,96 @@
+# Skillforge
+
+Skillforge turns successful agent traces into reusable skills.
+
+It compiles a source run into:
+
+- a portable `skill.contract.json`
+- an OpenClaw-friendly `SKILL.md`
+- a `verification.report.json`
+- example inputs for reuse
+
+The goal is simple: stop losing good agent work in transcripts. Capture what worked, parameterize it, attach approval gates, and make it reusable across OpenClaw or your own agent stack.
+
+## Why it exists
+
+Most agent tooling can execute one-off tasks, but successful runs usually die as logs. Skillforge promotes a successful trace into a reusable asset:
+
+- extract inputs like paths, URLs, repositories, dates, and emails
+- convert raw steps into a reusable execution plan
+- infer tool requirements and approval gates
+- export an installable markdown skill plus a portable JSON contract
+- statically verify that the generated skill can be re-rendered safely
+
+## Install
+
+```bash
+npm install
+npm run build
+```
+
+Or run the CLI directly in development:
+
+```bash
+npm run dev -- inspect examples/fix-flaky-test.trace.json
+```
+
+## CLI
+
+Compile a trace into a skill bundle:
+
+```bash
+npm run dev -- compile examples/fix-flaky-test.trace.json --out generated-skills
+```
+
+Inspect a trace without writing files:
+
+```bash
+npm run dev -- inspect examples/publish-weekly-report.trace.json
+```
+
+Verify a generated contract:
+
+```bash
+npm run dev -- verify generated-skills/fix-flaky-auth-test/skill.contract.json
+```
+
+List a local skill registry:
+
+```bash
+npm run dev -- list generated-skills
+```
+
+## Supported input shapes
+
+Skillforge accepts:
+
+- normalized trace JSON with `objective` + `steps`
+- objects containing `messages`
+- objects containing `events`, `entries`, or `trace`
+- JSONL event streams
+
+The compiler is intentionally conservative. It aims to create a useful reusable skill from incomplete data without executing any part of the source trace.
+
+## Output structure
+
+Each compiled skill bundle contains:
+
+- `skill.contract.json`: portable contract for any agent runtime
+- `SKILL.md`: Markdown skill for OpenClaw-style skill registries
+- `verification.report.json`: static verification result
+- `inputs.example.json`: extracted example values
+
+## Development
+
+```bash
+npm run check
+npm test
+npm run build
+```
+
+## Roadmap
+
+- adapter plugins for more agent trace formats
+- richer policy engines for command risk classification
+- replay-backed verification harnesses
+- registry publishing and trust receipts

examples/fix-flaky-test.trace.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "1.0",
+  "metadata": {
+    "source": "demo",
+    "title": "Fix flaky auth test"
+  },
+  "objective": "Fix the flaky test in tests/auth.spec.ts and verify it with npm test -- auth.",
+  "steps": [
+    {
+      "kind": "message",
+      "role": "user",
+      "content": "Fix the flaky test in tests/auth.spec.ts and make sure npm test -- auth passes."
+    },
+    {
+      "kind": "tool",
+      "tool": "read_file",
+      "input": {
+        "path": "tests/auth.spec.ts"
+      }
+    },
+    {
+      "kind": "tool",
+      "tool": "edit_file",
+      "input": {
+        "path": "tests/auth.spec.ts",
+        "instruction": "Replace the fixed sleep with a waitFor assertion."
+      }
+    },
+    {
+      "kind": "tool",
+      "tool": "bash",
+      "input": {
+        "command": "npm test -- auth"
+      }
+    },
+    {
+      "kind": "artifact",
+      "path": "tests/auth.spec.ts",
+      "summary": "Updated flaky test with deterministic waiting."
+    }
+  ]
+}

examples/publish-weekly-report.trace.json

@@ -0,0 +1,40 @@
+{
+  "metadata": {
+    "source": "demo",
+    "title": "Publish weekly report"
+  },
+  "objective": "Draft the weekly report in reports/weekly-2026-04-01.md from https://status.example.com and get approval before git commit.",
+  "steps": [
+    {
+      "kind": "message",
+      "role": "user",
+      "content": "Draft the weekly report in reports/weekly-2026-04-01.md from https://status.example.com."
+    },
+    {
+      "kind": "tool",
+      "tool": "web_fetch",
+      "input": {
+        "url": "https://status.example.com"
+      }
+    },
+    {
+      "kind": "tool",
+      "tool": "write_file",
+      "input": {
+        "path": "reports/weekly-2026-04-01.md",
+        "content": "# Weekly Report\n\nSummarize incidents and uptime."
+      }
+    },
+    {
+      "kind": "approval",
+      "reason": "Approve the generated report before making a commit."
+    },
+    {
+      "kind": "tool",
+      "tool": "bash",
+      "input": {
+        "command": "git commit -am \"weekly report\""
+      }
+    }
+  ]
+}

generated-skills/fix-flaky-auth-test/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: Fix Flaky Auth Test
+slug: fix-flaky-auth-test
+summary: Fix the flaky test in tests/auth.spec.ts and verify it with npm test -- auth.
+generated_by: skillforge
+trust_score: 92
+---
+
+# Fix Flaky Auth Test
+
+## Objective
+Fix the flaky test in tests/auth.spec.ts and verify it with npm test -- auth.
+
+## Inputs
+- `authSpecPath` (path): File or directory path detected in the source run. Example: `tests/auth.spec.ts`.
+- `authSpecTsRepository` (repo): Repository reference detected in the source run. Example: `tests/auth.spec.ts`.
+
+## Required Tools
+- `read_file`: read_file is a bounded trace step. Risk: low. Approval: none.
+- `edit_file`: edit_file changes files. Risk: medium. Approval: recommended.
+- `bash`: command `npm test -- auth` looks read-only or verification-focused. Risk: low. Approval: none.
+
+## Approval Gates
+- Approval recommended before run edit_file because edit_file changes files
+
+## Execution Plan
+1. Fix the flaky test in {{authSpecPath}} and verify it with npm test -- auth.
+2. Fix the flaky test in {{authSpecPath}} and make sure npm test -- auth passes.
+3. Read {{authSpecPath}}
+4. Modify {{authSpecPath}} with {
+  "instruction": "Replace the fixed sleep with a waitFor assertion.",
+  "path": "{{authSpecPath}}"
+}
+5. Run command: npm test -- auth
+6. Collect artifact {{authSpecPath}}: Updated flaky test with deterministic waiting.
+
+## Verification
+- `npm test -- auth`
+- `Collect artifact {{authSpecPath}}: Updated flaky test with deterministic waiting.`

generated-skills/fix-flaky-auth-test/inputs.example.json

@@ -0,0 +1,4 @@
+{
+  "authSpecPath": "tests/auth.spec.ts",
+  "authSpecTsRepository": "tests/auth.spec.ts"
+}