add the Skill.md file at the init command

Author: hamdymohamedak

.cursor/skills/runly/SKILL.md

@@ -43,6 +43,7 @@ npx runly init
 ```
 
 - Creates **`runly.config.js`** only if none of **`runly.config.mjs`**, **`runly.config.js`**, or **`runly.config.cjs`** exists (otherwise prints a message and exits **0**).
+- Writes **`SKILL.md`** in the project root when missing (Cursor agent skill template from the package); you may move it to **`.cursor/skills/runly/SKILL.md`**.
 - Uses **`export default`** when **`package.json`** has **`"type": "module"`**, else **`module.exports`**.
 - Adds **`"runly": "runly"`** under **`scripts`** in **`package.json`** when the file exists and **`scripts.runly`** is not already set.
 - Default **`run`** in the scaffold is a small **`node -e`** smoke command; edit to **`node --test`**, **`npm test`**, etc.
@@ -118,7 +119,7 @@ Exported types: **`RunlyConfig`**, **`RunlyRun`**. **`loadConfig(cwd?)`** loads
 
 | Command / flag | Meaning |
 |----------------|---------|
-| `runly init` | Scaffold **`runly.config.js`** and **`scripts.runly`** (see above). |
+| `runly init` | Scaffold **`runly.config.js`**, **`SKILL.md`** (if missing), and **`scripts.runly`** (see above). |
 | `runly` | Run matrix using config in cwd. |
 | `-c`, `--config` | Path to config file. |
 | `runly help` | Usage. |

.cursor/skills/runly/skill/SKILL.md

@@ -43,6 +43,7 @@ npx runly init
 ```
 
 - Creates **`runly.config.js`** only if none of **`runly.config.mjs`**, **`runly.config.js`**, or **`runly.config.cjs`** exists (otherwise prints a message and exits **0**).
+- Writes **`SKILL.md`** in the project root when missing (Cursor agent skill template from the package); you may move it to **`.cursor/skills/runly/SKILL.md`**.
 - Uses **`export default`** when **`package.json`** has **`"type": "module"`**, else **`module.exports`**.
 - Adds **`"runly": "runly"`** under **`scripts`** in **`package.json`** when the file exists and **`scripts.runly`** is not already set.
 - Default **`run`** in the scaffold is a small **`node -e`** smoke command; edit to **`node --test`**, **`npm test`**, etc.
@@ -118,7 +119,7 @@ Exported types: **`RunlyConfig`**, **`RunlyRun`**. **`loadConfig(cwd?)`** loads
 
 | Command / flag | Meaning |
 |----------------|---------|
-| `runly init` | Scaffold **`runly.config.js`** and **`scripts.runly`** (see above). |
+| `runly init` | Scaffold **`runly.config.js`**, **`SKILL.md`** (if missing), and **`scripts.runly`** (see above). |
 | `runly` | Run matrix using config in cwd. |
 | `-c`, `--config` | Path to config file. |
 | `runly help` | Usage. |

README.md

@@ -30,13 +30,13 @@ The executable name is **`runly`** (see `bin` in `package.json`).
 
 ### First-time setup (`init`)
 
-From your project root, create a default `runly.config.js` and add an npm script **`runly`** when `package.json` exists:
+From your project root, create a default `runly.config.js`, a **`SKILL.md`** agent-skill template (when `SKILL.md` is not already present), and add an npm script **`runly`** when `package.json` exists:
 
 ```bash
 npx runly init
 ```
 
-If any of `runly.config.mjs`, `runly.config.js`, or `runly.config.cjs` already exists, `init` does nothing (idempotent).
+If any of `runly.config.mjs`, `runly.config.js`, or `runly.config.cjs` already exists, `init` does nothing for the config (idempotent). Existing **`SKILL.md`** is never overwritten.
 
 ### Run the matrix
 
@@ -141,7 +141,7 @@ Exported types include `RunlyConfig` and `RunlyRun`. **`loadConfig(cwd?)`** load
 
 | Command / flag | Description |
 |----------------|-------------|
-| `runly init` | Create `runly.config.js` with defaults and add `"runly": "runly"` to `package.json` when present. No-op if a config file already exists. |
+| `runly init` | Create `runly.config.js` with defaults, copy **`SKILL.md`** when missing, and add `"runly": "runly"` to `package.json` when present. No-op for config if a config file already exists. |
 | `runly`, `runly -c <path>` | Run the matrix (search for config in cwd, or use `-c` / `--config`). |
 | `-c`, `--config` | Path to a config file. If omitted, Runly searches for `runly.config.mjs`, then `.js`, then `.cjs` in the current working directory. |
 | `runly help` | Print usage. |

dist/cli.js

@@ -1,6 +1,5 @@
 /**
- * Create `runly.config.js` with defaults and add `"runly": "runly"` to package.json when possible.
+ * Create `runly.config.js` with defaults, copy `SKILL.md` when absent, and add `"runly": "runly"` to package.json when possible.
  * @returns `"exists"` if any runly config file is already present, otherwise `"created"`.
  */
 export declare function initRunlyProject(cwd: string): "exists" | "created";
-//# sourceMappingURL=init.d.ts.map

dist/init.d.ts

@@ -1,8 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { hasAnyRunlyConfig } from "./config-paths.js";
 const PKG = "@hamdymohamedak/runly";
 const DEFAULT_FILE = "runly.config.js";
+const SKILL_FILE = "SKILL.md";
 function readPkgJson(cwd) {
     const p = join(cwd, "package.json");
     if (!existsSync(p))
@@ -23,7 +25,6 @@ function defaultConfigBody() {
     shell: false,
   },
 }`;
-}
 function tryAddRunlyScriptToDisk(cwd) {
     const pkgPath = join(cwd, "package.json");
     if (!existsSync(pkgPath))
@@ -45,10 +46,26 @@ function tryAddRunlyScriptToDisk(cwd) {
     pkg.scripts = scripts;
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 }
-/**
- * Create `runly.config.js` with defaults and add `"runly": "runly"` to package.json when possible.
- * @returns `"exists"` if any runly config file is already present, otherwise `"created"`.
- */
+function bundledSkillTemplatePath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const packageRoot = join(here, "..");
+    const p = join(packageRoot, "templates", SKILL_FILE);
+    return existsSync(p) ? p : null;
+}
+function tryWriteSkillTemplate(cwd) {
+    const target = join(cwd, SKILL_FILE);
+    if (existsSync(target))
+        return;
+    const src = bundledSkillTemplatePath();
+    if (!src)
+        return;
+    try {
+        writeFileSync(target, readFileSync(src, "utf8"));
+    }
+    catch {
+        /* ignore */
+    }
+}
 export function initRunlyProject(cwd) {
     if (hasAnyRunlyConfig(cwd))
         return "exists";
@@ -59,7 +76,7 @@ export function initRunlyProject(cwd) {
         ? `/** @type {import("${PKG}").RunlyConfig} */\nexport default ${body};\n`
         : `/** @type {import("${PKG}").RunlyConfig} */\nmodule.exports = ${body};\n`;
     writeFileSync(join(cwd, DEFAULT_FILE), content, "utf8");
+    tryWriteSkillTemplate(cwd);
     tryAddRunlyScriptToDisk(cwd);
     return "created";
 }
-//# sourceMappingURL=init.js.map

dist/init.js

@@ -1,6 +1,6 @@
 {
   "name": "@hamdymohamedak/runly",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates/SKILL.md"
   ],
   "scripts": {
     "test": "node --test test/smoke.test.js",

package.json

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * CI: pack this repo, install tarball into fresh consumers, run `runly init`, assert
- * runly.config.js + scripts.runly, then `npm run runly`.
+ * runly.config.js + SKILL.md + scripts.runly, then `npm run runly`.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
@@ -49,6 +49,16 @@ function verifyConsumer(label, pkgJson, assertConfig) {
   }
   assertConfig(readFileSync(cfg, "utf8"));
 
+  const skill = join(consumer, "SKILL.md");
+  if (!existsSync(skill)) {
+    console.error(`[${label}] missing SKILL.md after runly init`);
+    process.exit(1);
+  }
+  if (!readFileSync(skill, "utf8").includes("name: runly")) {
+    console.error(`[${label}] SKILL.md looks invalid`);
+    process.exit(1);
+  }
+
   const installed = JSON.parse(readFileSync(join(consumer, "package.json"), "utf8"));
   if (installed.scripts?.runly !== "runly") {
     console.error(`[${label}] expected scripts.runly === "runly", got:`, installed.scripts);

scripts/ci-verify-init.mjs

@@ -49,7 +49,7 @@ async function main() {
       process.exit(0);
     }
     console.error(
-      "Created runly.config.js with default matrix. Added npm script \"runly\" if package.json is present.",
+      "Created runly.config.js with default matrix, SKILL.md (if missing), and npm script \"runly\" if package.json is present.",
     );
     process.exit(0);
   }

src/cli.ts

@@ -1,9 +1,11 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { hasAnyRunlyConfig } from "./config-paths.js";
 
 const PKG = "@hamdymohamedak/runly";
 const DEFAULT_FILE = "runly.config.js";
+const SKILL_FILE = "SKILL.md";
 
 function readPkgJson(cwd: string) {
   const p = join(cwd, "package.json");
@@ -46,8 +48,29 @@ function tryAddRunlyScriptToDisk(cwd: string): void {
   writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 }
 
+/** Path to bundled `templates/SKILL.md` inside the installed package (next to `dist/`). */
+function bundledSkillTemplatePath(): string | null {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const packageRoot = join(here, "..");
+  const p = join(packageRoot, "templates", SKILL_FILE);
+  return existsSync(p) ? p : null;
+}
+
+/** Copy agent skill template next to config; skip if `SKILL.md` already exists. */
+function tryWriteSkillTemplate(cwd: string): void {
+  const target = join(cwd, SKILL_FILE);
+  if (existsSync(target)) return;
+  const src = bundledSkillTemplatePath();
+  if (!src) return;
+  try {
+    writeFileSync(target, readFileSync(src, "utf8"));
+  } catch {
+    /* ignore missing or unreadable template */
+  }
+}
+
 /**
- * Create `runly.config.js` with defaults and add `"runly": "runly"` to package.json when possible.
+ * Create `runly.config.js` with defaults, copy `SKILL.md` when absent, and add `"runly": "runly"` to package.json when possible.
  * @returns `"exists"` if any runly config file is already present, otherwise `"created"`.
  */
 export function initRunlyProject(cwd: string): "exists" | "created" {
@@ -61,6 +84,7 @@ export function initRunlyProject(cwd: string): "exists" | "created" {
     : `/** @type {import("${PKG}").RunlyConfig} */\nmodule.exports = ${body};\n`;
 
   writeFileSync(join(cwd, DEFAULT_FILE), content, "utf8");
+  tryWriteSkillTemplate(cwd);
   tryAddRunlyScriptToDisk(cwd);
   return "created";
 }