@hasna/skills 0.1.59 → 0.1.61

package/skills/security-audit-report/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: security-audit-report
-description: Generate a premium security hardening report covering auth, secrets, headers, webhooks, RLS, permissions, dependency risk, and prioritized fixes.
+description: Generate a security hardening report covering auth, secrets, headers, webhooks, RLS, permissions, dependency risk, and prioritized fixes.
+kind: instruction
 ---
 
 # Security Audit Report
@@ -9,32 +10,43 @@ Generate a security hardening package for SaaS and developer tooling projects.
 
 ## Requirements
 
-- Authenticate with `skills auth login`.
-- This premium skill runs through the hosted Skills runtime; local installs expose only metadata and instructions.
+None. This is an instruction skill: it is prose an agent follows, so it needs no
+credentials, no network access, and no local runtime.
 
 ## Usage
 
-```bash
-skills run security-audit-report --target ./app --scope "auth,secrets,headers,webhooks,rls"
-skills run security-audit-report --target ./src --framework "Next.js"
-```
+Ask an agent for the deliverables below and give it the inputs. Reading this file
+IS the invocation; `skills run` refuses instruction skills on purpose.
 
-## Options
+## Inputs
 
-| Option | Description | Default |
+| Input | Description | Default |
 |--------|-------------|---------|
-| `--target <path>` | Directory to inspect. | current directory |
-| `--scope <list>` | Comma-separated focus areas. | auth,secrets,headers,webhooks,rls,permissions,dependencies |
-| `--framework <name>` | App stack context for recommendations. | generic web app |
-| `--output <dir>` | Output directory for direct local execution. Hosted runs use the run export directory. | run export dir |
+| `target` | Directory to inspect. | current directory |
+| `scope` | Comma-separated focus areas. | auth,secrets,headers,webhooks,rls,permissions,dependencies |
+| `framework` | App stack context for recommendations. | generic web app |
 
-## Outputs
+## Deliverables
 
 - `security-audit-report.md`
-- `security-audit-report.pdf`
 - `findings.json`
 - `findings.csv`
 - `remediation-plan.md`
 - `manifest.json`
 
-After submitting a hosted run, poll with `skills runs status <run-id>` and download outputs with `skills exports download <run-id>`.
+## Method
+
+1. Scope explicitly: what you inspected, what you could not, and the date. An
+   audit silently missing a subsystem is dangerous.
+2. Work the scope areas in order (auth, secrets, transport and headers, webhooks,
+   row-level security, permissions, dependencies) and record a finding or an
+   explicit "no issue found" for each.
+3. Rate severity by exploitability and blast radius together, and justify the
+   rating in one line.
+4. For each finding: the vulnerable pattern, where it occurs, what an attacker
+   gains, and concrete remediation code or configuration.
+5. For dependency risk, run the project's own auditor (`npm audit`,
+   `bun audit`, `pip-audit`) and report its real output rather than guessing.
+6. Order the remediation plan by risk reduction per unit of effort.
+7. State clearly that this is a review, not a penetration test, and name what
+   still requires one.

package/skills/security-audit-report/package.json

@@ -2,10 +2,9 @@
   "name": "security-audit-report",
   "version": "0.1.0",
   "private": true,
-  "description": "Generate security hardening report artifacts through the hosted Skills runtime",
+  "description": "Generate security hardening report artifacts",
   "type": "module",
   "skills": {
-    "runtime": "hosted",
-    "source": "remote"
+    "kind": "instruction"
   }
 }

package/skills/seo-content-pack/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: seo-content-pack
-description: Generate premium SEO content packages with topic clusters, articles, metadata, links, FAQs, and publishing cadence.
+description: Generate SEO content packages with topic clusters, articles, metadata, links, FAQs, and publishing cadence.
+kind: instruction
 ---
 
 # SEO Content Pack
@@ -9,28 +10,25 @@ Generate a complete SEO content package from a topic, audience, and product cont
 
 ## Requirements
 
-- Authenticate with `skills auth login`.
-- This premium skill runs through the hosted Skills runtime; local installs expose only metadata and instructions.
+None. This is an instruction skill: it is prose an agent follows, so it needs no
+credentials, no network access, and no local runtime.
 
 ## Usage
 
-```bash
-skills run seo-content-pack --topic "usage-based billing for AI SaaS" --audience "founders and operators"
-skills run seo-content-pack "developer onboarding automation" --brand "Acme" --articles 5
-```
+Ask an agent for the deliverables below and give it the inputs. Reading this file
+IS the invocation; `skills run` refuses instruction skills on purpose.
 
-## Options
+## Inputs
 
-| Option | Description | Default |
+| Input | Description | Default |
 |--------|-------------|---------|
-| `--topic <text>` | Core topic or search theme. Positional text also works. | required |
-| `--brand <name>` | Brand or product name. | Brand |
-| `--audience <text>` | Target audience. | SaaS buyers |
-| `--articles <n>` | Supporting article count, 3-8. | 5 |
-| `--tone <tone>` | `practical`, `executive`, or `technical`. | practical |
-| `--output <dir>` | Output directory for direct local execution. Hosted runs use the run export directory. | run export dir |
+| `topic` | Core topic or search theme. Positional text also works. | required |
+| `brand` | Brand or product name. | Brand |
+| `audience` | Target audience. | SaaS buyers |
+| `articles` | Supporting article count, 3-8. | 5 |
+| `tone` | `practical`, `executive`, or `technical`. | practical |
 
-## Outputs
+## Deliverables
 
 - `topic-cluster.md`
 - `pillar-article.md`
@@ -41,4 +39,16 @@ skills run seo-content-pack "developer onboarding automation" --brand "Acme" --a
 - `publishing-cadence.csv`
 - `manifest.json`
 
-After submitting a hosted run, poll with `skills runs status <run-id>` and download outputs with `skills exports download <run-id>`.
+## Method
+
+1. Build the topic cluster around search intent, with one pillar and supporting
+   pages that each own a distinct sub-intent. Overlapping pages cannibalize.
+2. For each page, record the primary query, the intent type, and the specific
+   question it answers better than the current top results.
+3. Write the pillar in full; outline the supporting pages to H2 level with the
+   angle each takes.
+4. Produce titles and meta descriptions within real pixel limits, front-loading
+   the query.
+5. Specify internal links in both directions with the anchor text to use.
+6. Answer FAQs in the first two sentences of each answer, then elaborate.
+7. Set a publishing cadence that matches the team's actual capacity.

package/skills/seo-content-pack/package.json

@@ -5,7 +5,6 @@
   "description": "Hosted skill metadata for seo-content-pack",
   "type": "module",
   "skills": {
-    "runtime": "hosted",
-    "source": "remote"
+    "kind": "instruction"
   }
 }

package/skills/slide-deck-generator/SKILL.md

@@ -1,44 +1,93 @@
 ---
 name: slide-deck-generator
-description: Generate premium slide decks from briefs, docs, or outlines with PPTX/PDF artifacts, speaker notes, theme guidance, structured slide metadata, and manifest metadata.
+description: Turn a brief or Markdown outline into a real slide deck locally - structured slides.json, deck.md, speaker notes, theme guide, a self-contained keyboard-navigable HTML deck, and a PPTX file.
 ---
 
 # Slide Deck Generator
 
-Generate an editable slide deck package from a brief, document excerpt, outline, product narrative, training plan, report, or proposal.
+Parse a brief, outline, report, or product narrative into a slide model, then render it to several
+formats at once. This is the local binary renderer: it does the deterministic parsing, layout, and
+file writing so no model call is needed to produce the artifacts.
+
+`pitch-deck` is an instruction skill that decides the narrative and then delegates the actual
+rendering to this skill. Anything that needs a real `.pptx` or a shareable HTML deck should call
+`slide-deck-generator`.
+
+Everything runs locally. No API keys, no network calls, no accounts.
 
 ## Requirements
 
-- Authenticate with `skills auth login`.
-- This premium skill runs through the hosted Skills runtime; local installs expose only metadata and instructions.
+- [Bun](https://bun.sh) 1.1+.
+- `bun install` inside this skill directory. Runtime dependencies:
+  - `marked` — Markdown tokenizing for `--source` outlines.
+  - `pptxgenjs` — writes the real `deck.pptx` (Open XML zip package).
+- No API keys and no network access. `deck.html` embeds all CSS and JS inline and makes zero
+  external requests.
 
 ## Usage
 
 ```bash
-skills run slide-deck-generator --brief "Q2 launch review for AI billing" --title "Q2 Launch Review" --audience executives
-skills run slide-deck-generator ./outline.md --format training --slides 12
+# From a Markdown outline
+bun run src/index.ts --source ./outline.md --slides 10 --theme aurora \
+  --audience executives --format report --output ./out
+
+# From a one-paragraph brief
+bun run src/index.ts --brief "Q2 launch review for AI billing" --slides 8 --theme midnight
+
+# Skip PPTX rendering, emit machine-readable manifest
+bun run src/index.ts --source ./outline.md --no-pptx --json
 ```
 
+Open `out/deck.html` in any browser: `←`/`→` (or space) to navigate, `Home`/`End` to jump, `N` to
+toggle speaker notes, `Ctrl/Cmd-P` to print one slide per page.
+
+### Markdown parsing rules
+
+- The first `#` heading becomes the deck title (unless `--title` is given).
+- Each `#`/`##` heading starts a new slide; `###` headings become bullets.
+- List items become bullets; paragraphs become speaker notes (and become bullets when a slide would
+  otherwise be empty); blockquotes become full-bleed quote slides; the first lines of a code block
+  become bullets.
+- Plain prose with no Markdown structure is split into sentences and grouped into slides.
+- The deck is then fitted to `--slides`: dense slides split into `(cont.)` slides, short adjacent
+  slides merge, and any remaining gap is filled with format-appropriate scaffold slides.
+
 ## Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--brief <text>` | Brief, outline, or source text. Positional text also works. | required |
-| `--source <path>` | Read brief text from a file. | none |
-| `--title <text>` | Deck title. | Slide Deck |
-| `--audience <type>` | `team`, `customers`, `executives`, or `students`. | team |
-| `--format <type>` | `general`, `training`, `sales`, `report`, or `proposal`. | general |
-| `--slides <n>` | Number of slides. | 8 |
-| `--output <dir>` | Output directory for direct local execution. Hosted runs use the run export directory. | run export dir |
+| `-b, --brief <text>` | Brief, outline, or narrative text. Also accepted as a bare positional argument. | — |
+| `-s, --source <path>` | Read the brief/outline from a Markdown or text file. | — |
+| `-t, --title <text>` | Deck title. | first `#` heading, else first line of the brief |
+| `-n, --slides <n>` | Target slide count (1–60). | `8` |
+| `--theme <name>` | `midnight`, `aurora`, `sandstone`, `ocean`, or `mono`. | `midnight` |
+| `--audience <type>` | `team`, `customers`, `executives`, or `students`. Shapes the speaker notes. | `team` |
+| `--format <type>` | `general`, `training`, `sales`, `report`, or `proposal`. Shapes the closing slides. | `general` |
+| `-o, --output <dir>` | Output directory. | `./slide-deck` |
+| `--no-pptx` | Skip `deck.pptx`; still write every other file. | off |
+| `--json` | Print `manifest.json` to stdout instead of the text summary. | off |
+| `-h, --help` | Show help. | — |
+| `-v, --version` | Show version. | — |
+
+Either `--brief` or `--source` is required.
 
 ## Outputs
 
-- `deck.md`
-- `deck.pdf`
-- `deck.pptx`
-- `slides.json`
-- `speaker-notes.md`
-- `theme-guide.md`
-- `manifest.json`
+Written under `--output`:
+
+| File | Contents |
+|------|----------|
+| `slides.json` | The slide model: index, layout (`title`/`agenda`/`bullets`/`section`/`quote`/`closing`), title, subtitle, bullets, and notes per slide. |
+| `deck.md` | Readable Markdown deck, one `---` separated section per slide with inline notes. |
+| `speaker-notes.md` | Per-slide talk track, on-screen recap, runtime estimate, and a delivery checklist. |
+| `theme-guide.md` | Palette hex values, typography scale, layout rules, and how to swap themes. |
+| `deck.html` | Self-contained reveal-style deck: inline CSS/JS, keyboard + click navigation, progress bar, notes toggle, and a print stylesheet that paginates one slide per page. No external requests. |
+| `deck.pptx` | Real PowerPoint file written by `pptxgenjs` (16:9), including per-slide speaker notes. Opens in PowerPoint, Keynote, LibreOffice, and Google Slides. |
+| `manifest.json` | Run metadata: title, source, theme, audience, format, slide count, layouts, and file list. |
+
+## Notes
 
-After submitting a hosted run, poll with `skills runs status <run-id>` and download outputs with `skills exports download <run-id>`.
+- PPTX rendering failures are non-fatal: the other files are still written, a warning goes to
+  stderr, and `manifest.json` records `pptx: "failed: …"`.
+- Scaffold slides added to reach `--slides` are labelled in their notes so they are easy to find and
+  replace before presenting.

package/skills/slide-deck-generator/package.json

@@ -2,10 +2,37 @@
   "name": "slide-deck-generator",
   "version": "0.1.0",
   "private": true,
-  "description": "Hosted premium slide deck generator",
+  "description": "Turn a brief or markdown outline into a real slide deck: slides.json, deck.md, speaker notes, theme guide, self-contained HTML, and a PPTX file",
   "type": "module",
-  "skills": {
-    "runtime": "hosted",
-    "source": "remote"
+  "main": "src/index.ts",
+  "bin": {
+    "slide-deck-generator": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "slides",
+    "deck",
+    "pptx",
+    "powerpoint",
+    "presentation",
+    "markdown",
+    "cli",
+    "skill"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "marked": "^15.0.0",
+    "pptxgenjs": "^3.12.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
   }
 }

package/skills/slide-deck-generator/src/cli.ts

@@ -0,0 +1,133 @@
+import { AUDIENCES, FORMATS, THEMES, type CliOptions } from "./types.js";
+
+const VERSION = "0.1.0";
+
+function printHelp(): void {
+  console.log(`slide-deck-generator v${VERSION}
+
+USAGE:
+  slide-deck-generator --brief "<text>" [options]
+  slide-deck-generator --source <outline.md> [options]
+
+OPTIONS:
+  -b, --brief <text>      Brief, outline, or narrative text. A bare positional also works.
+  -s, --source <path>     Read the brief/outline from a Markdown or text file.
+  -t, --title <text>      Deck title (default: first heading, or first line of the brief)
+  -n, --slides <n>        Target slide count (default: 8)
+      --theme <name>      ${Object.keys(THEMES).join(" | ")} (default: midnight)
+      --audience <type>   ${AUDIENCES.join(" | ")} (default: team)
+      --format <type>     ${FORMATS.join(" | ")} (default: general)
+  -o, --output <dir>      Output directory (default: ./slide-deck)
+      --no-pptx           Skip deck.pptx rendering (all other files still emitted)
+      --json              Print the manifest as JSON instead of a text summary
+  -h, --help              Show this help message
+  -v, --version           Show the current version
+
+EXAMPLES:
+  slide-deck-generator --brief "Q2 launch review for AI billing" --slides 10 --theme aurora
+  slide-deck-generator --source ./outline.md --audience executives --output ./out
+`);
+}
+
+export function parseArgs(argv: string[]): CliOptions {
+  const options: CliOptions = {
+    audience: "team",
+    format: "general",
+    slides: 8,
+    theme: "midnight",
+    output: "./slide-deck",
+    json: false,
+    noPptx: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    switch (arg) {
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      case "--version":
+      case "-v":
+        console.log(VERSION);
+        process.exit(0);
+      case "--brief":
+      case "-b":
+        options.brief = argv[++i];
+        break;
+      case "--source":
+      case "-s":
+        options.source = argv[++i];
+        break;
+      case "--title":
+      case "-t":
+        options.title = argv[++i];
+        break;
+      case "--slides":
+      case "-n": {
+        const value = Number.parseInt(argv[++i] ?? "", 10);
+        if (!Number.isFinite(value) || value < 1 || value > 60) {
+          throw new Error(`Invalid --slides value: ${argv[i]}. Use 1-60.`);
+        }
+        options.slides = value;
+        break;
+      }
+      case "--theme": {
+        const value = (argv[++i] ?? "").toLowerCase();
+        if (!THEMES[value]) {
+          throw new Error(`Unknown --theme: ${value}. Available: ${Object.keys(THEMES).join(", ")}`);
+        }
+        options.theme = value;
+        break;
+      }
+      case "--audience": {
+        const value = (argv[++i] ?? "").toLowerCase();
+        if (!AUDIENCES.includes(value)) {
+          throw new Error(`Unknown --audience: ${value}. Available: ${AUDIENCES.join(", ")}`);
+        }
+        options.audience = value;
+        break;
+      }
+      case "--format": {
+        const value = (argv[++i] ?? "").toLowerCase();
+        if (!FORMATS.includes(value)) {
+          throw new Error(`Unknown --format: ${value}. Available: ${FORMATS.join(", ")}`);
+        }
+        options.format = value;
+        break;
+      }
+      case "--output":
+      case "-o":
+        options.output = argv[++i] ?? "./slide-deck";
+        break;
+      case "--no-pptx":
+        options.noPptx = true;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`Unknown option: ${arg}`);
+        }
+        if (!options.brief && !options.source) {
+          options.brief = arg;
+          break;
+        }
+        throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  if (!options.brief && !options.source) {
+    throw new Error("Provide --brief <text> or --source <file>. See --help.");
+  }
+
+  return options;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Text helpers                                                                */
+/* -------------------------------------------------------------------------- */
+
+

package/skills/slide-deck-generator/src/index.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+
+import { parseArgs } from "./cli.js";
+import { buildSlides, draftsFromBrief, parseMarkdown, type DraftSlide } from "./model.js";
+import { renderPptx } from "./pptx.js";
+import {
+  renderDeckMarkdown,
+  renderHtml,
+  renderSpeakerNotes,
+  renderThemeGuide,
+} from "./render.js";
+import { THEMES } from "./types.js";
+import { shorten, stripInlineMarkdown, titleCase } from "./utils.js";
+
+const VERSION = "0.1.0";
+
+async function writeOut(root: string, relativePath: string, contents: string): Promise<string> {
+  const target = join(root, relativePath);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, contents, "utf8");
+  return relativePath;
+}
+
+async function main(): Promise<void> {
+  const options = parseArgs(process.argv.slice(2));
+  const theme = THEMES[options.theme];
+
+  let sourceText = options.brief ?? "";
+  let sourceLabel = "brief";
+  if (options.source) {
+    const sourcePath = resolve(options.source);
+    try {
+      sourceText = await readFile(sourcePath, "utf8");
+    } catch {
+      throw new Error(`Unable to read source file: ${sourcePath}`);
+    }
+    sourceLabel = sourcePath;
+  }
+
+  if (!sourceText.trim()) {
+    throw new Error("Source text is empty. Nothing to build a deck from.");
+  }
+
+  const looksLikeMarkdown = /^\s*#|^\s*[-*+]\s+|^\s*\d+\.\s+/m.test(sourceText);
+  let deckTitle = options.title;
+  let drafts: DraftSlide[];
+
+  if (looksLikeMarkdown) {
+    const parsed = await parseMarkdown(sourceText);
+    deckTitle = deckTitle ?? parsed.deckTitle;
+    drafts = parsed.drafts;
+    if (drafts.length === 0) drafts = draftsFromBrief(sourceText);
+  } else {
+    drafts = draftsFromBrief(sourceText);
+  }
+
+  if (!deckTitle) {
+    const firstLine = sourceText.split("\n").map((line) => stripInlineMarkdown(line)).find(Boolean) ?? "Slide Deck";
+    deckTitle = titleCase(shorten(firstLine, 70));
+  }
+
+  if (drafts.length === 0) {
+    throw new Error("Could not derive any slides from the source text.");
+  }
+
+  const slides = buildSlides(deckTitle, drafts, options);
+  const outputRoot = resolve(options.output);
+  const written: string[] = [];
+
+  const slidesJson = {
+    title: deckTitle,
+    theme: theme.name,
+    audience: options.audience,
+    format: options.format,
+    slideCount: slides.length,
+    slides,
+  };
+
+  written.push(await writeOut(outputRoot, "slides.json", `${JSON.stringify(slidesJson, null, 2)}\n`));
+  written.push(await writeOut(outputRoot, "deck.md", renderDeckMarkdown(deckTitle, slides, theme, options)));
+  written.push(await writeOut(outputRoot, "speaker-notes.md", renderSpeakerNotes(deckTitle, slides, options)));
+  written.push(await writeOut(outputRoot, "theme-guide.md", renderThemeGuide(theme, slides)));
+  written.push(await writeOut(outputRoot, "deck.html", renderHtml(deckTitle, slides, theme, options)));
+
+  let pptxError: string | undefined;
+  if (!options.noPptx) {
+    await mkdir(outputRoot, { recursive: true });
+    try {
+      await renderPptx(join(outputRoot, "deck.pptx"), deckTitle, slides, theme, options);
+      written.push("deck.pptx");
+    } catch (error) {
+      pptxError = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const manifest = {
+    skill: "slide-deck-generator",
+    skillVersion: VERSION,
+    generatedAt: new Date().toISOString(),
+    title: deckTitle,
+    source: options.source ? { type: "file", path: sourceLabel } : { type: "brief", chars: sourceText.length },
+    theme: theme.name,
+    audience: options.audience,
+    format: options.format,
+    slideCount: slides.length,
+    layouts: slides.map((slide) => slide.layout),
+    outputDir: outputRoot,
+    files: [...written, "manifest.json"].sort(),
+    pptx: options.noPptx ? "skipped" : pptxError ? `failed: ${pptxError}` : "ok",
+  };
+
+  written.push(await writeOut(outputRoot, "manifest.json", `${JSON.stringify(manifest, null, 2)}\n`));
+
+  if (pptxError) {
+    process.stderr.write(`slide-deck-generator: warning: deck.pptx was not written (${pptxError})\n`);
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+    return;
+  }
+
+  console.log(
+    [
+      `slide-deck-generator v${VERSION}`,
+      `  title      ${deckTitle}`,
+      `  source     ${options.source ? basename(sourceLabel) : `brief (${sourceText.length} chars)`}`,
+      `  theme      ${theme.label} (${theme.name})`,
+      `  audience   ${options.audience} · format ${options.format}`,
+      `  slides     ${slides.length}`,
+      `  output     ${outputRoot}`,
+      "",
+      "Files:",
+      ...manifest.files.map((file) => `  ${file}`),
+      "",
+      `Open the deck: ${join(outputRoot, "deck.html")} (← → to navigate, N for notes, Ctrl/Cmd-P to print)`,
+    ].join("\n"),
+  );
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`slide-deck-generator: ${message}\n`);
+  process.exit(1);
+});