@hasna/skills 0.1.60 → 0.1.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
   "files": [
     "dist/",
     "!dist/**/*.test.d.ts",
+    "!dist/test-preload.d.ts",
     "!dist/platform",
     "!dist/server",
     "bin/",
@@ -30,8 +31,7 @@
     "docs/skill-standard.md",
     "skills/",
     "!skills/**/node_modules",
-    "!skills/scaffold-project/my-app",
-    "!skills/{ad-creative-pack,api-docs-portal,audio,audio-transcript-pack,blog-article,brand-kit,brand-photo-shoot,browse,contract-review-report,customer-feedback-report,deepresearch,email-sequence,generate-book-cover,icon-pack,image,invoice-reconciliation,landing-page-pack,logo-design,market-research-report,meeting-pack,migration-plan-pack,music,music-album,one-page-website,pdf-read,pdf-to-dataset,pdf-to-markdown,performance-audit-report,photo-album,pitch-deck,playlist-maker,product-mockup,proposal-pack,read-pdf,remove-background,repo-onboarding-report,sdk-generator,security-audit-report,seo-content-pack,short-video-pack,slide-deck-generator,social-content-calendar,test-suite-generator,transcript,video,video-highlight-pack,voiceover-jingle-pack,webcrawling}/src",
+    "agent-skills/",
     "LICENSE",
     "README.md"
   ],
@@ -40,7 +40,7 @@
   "scripts": {
     "clean": "rm -rf bin/ dist/",
     "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
-    "test": "bun test",
+    "test": "bun test --timeout 30000",
     "dev": "bun run ./src/cli/index.tsx",
     "dev:watch": "bun --watch run ./src/cli/index.tsx",
     "dev:mcp": "bun --watch run ./src/mcp/index.ts",

package/skills/_common/http-client.ts

@@ -5,7 +5,14 @@
  * Usage: import and call executeSkill() from your skill CLI
  */
 
-const SKILL_API_URL = process.env.SKILLS_API_URL || process.env.SKILL_API_URL || "https://skills.md/api/v1";
+// No default endpoint. An unconfigured install has no instance to talk to, and
+// guessing one would send this skill's payload and API key to a host the
+// operator never chose.
+const SKILL_API_URL = process.env.SKILLS_API_URL || process.env.SKILL_API_URL || "";
+
+const MISSING_API_URL_MESSAGE =
+  "Set SKILLS_API_URL to the origin of the Skills instance you run, " +
+  "or run `skills setup --api-url <origin>`";
 
 export interface SkillRequest {
   skill: string;
@@ -30,6 +37,14 @@ export interface SkillResponse {
 export async function executeSkill(request: SkillRequest): Promise<SkillResponse | Blob> {
   const { skill, ...params } = request;
 
+  if (!SKILL_API_URL) {
+    return {
+      success: false,
+      error: "Missing SKILLS_API_URL",
+      details: MISSING_API_URL_MESSAGE,
+    };
+  }
+
   const url = `${SKILL_API_URL}/${skill}/`;
 
   // Get API key from environment
@@ -95,7 +110,7 @@ export async function saveBlob(blob: Blob, outputPath: string): Promise<void> {
  * Helper to execute a skill and save file if needed
  */
 export async function executeAndSave(request: SkillRequest): Promise<boolean> {
-  console.log(`🔗 Connecting to ${SKILL_API_URL}...`);
+  if (SKILL_API_URL) console.log(`🔗 Connecting to ${SKILL_API_URL}...`);
 
   const result = await executeSkill(request);
 

package/skills/_common/install.sh

@@ -2,6 +2,6 @@
 set -euo pipefail
 
 echo "Direct per-skill installers are disabled."
-echo "Register the shared Skills MCP server instead:"
-echo "  skills mcp --register all"
+echo "Render skills into native agent folders instead:"
+echo "  skills render"
 exit 1

package/skills/_common/installer.ts

@@ -3,9 +3,8 @@
 /**
  * Legacy per-skill installer boundary.
  *
- * Agent-native skill folders are intentionally unmanaged. Skills are exposed
- * through the root Skills CLI/MCP server so local agents discover the catalog
- * without receiving copied source, package files, or SKILL.md files.
+ * Agent-native skill folders are intentionally unmanaged by legacy installers.
+ * The root Skills CLI renders skills into those folders instead.
  */
 
 export interface SkillConfig {
@@ -38,7 +37,7 @@ export class SkillInstaller {
   async uninstall(assistant: AssistantType): Promise<void> {
     throw new Error(
       `Direct agent skill-folder uninstalls are disabled for ${this.config.name}. ` +
-        `Skills MCP owns discovery; update MCP registration with: skills mcp --register ${assistant}`,
+        "Render skills into native agent folders instead: skills render",
     );
   }
 }
@@ -68,6 +67,6 @@ export async function runInstaller(
 function registrationMessage(skillName: string, assistant: AssistantType): string {
   return (
     `Direct agent skill-folder installs are disabled for ${skillName}. ` +
-    `Register the Skills MCP server instead: skills mcp --register ${assistant}`
+    "Render skills into native agent folders instead: skills render"
   );
 }

package/skills/_common/skill-install.ts

@@ -2,7 +2,7 @@
  * Legacy install command boundary for bundled skill packages.
  *
  * Per-skill packages must not write into agent-native skill directories.
- * Discovery and execution go through the root Skills CLI/MCP server.
+ * The root Skills CLI renders skills into agent-native skill directories.
  */
 
 interface SkillMeta {
@@ -23,7 +23,7 @@ export async function handleInstallCommand(meta: SkillMeta, args: string[]): Pro
 
   if (!assistant || !["claude", "codex", "windsurf", "cursor"].includes(assistant)) {
     console.error("Direct per-skill installs are disabled.");
-    console.error("Use: skills mcp --register <claude|codex|windsurf|cursor|all>");
+    console.error("Use: skills render");
     process.exit(1);
   }
 
@@ -32,6 +32,6 @@ export async function handleInstallCommand(meta: SkillMeta, args: string[]): Pro
   } else {
     console.error(`Direct uninstalls for ${meta.name} are disabled.`);
   }
-  console.error(`Use: skills mcp --register ${assistant}`);
+  console.error("Use: skills render");
   process.exit(1);
 }

package/skills/ad-creative-pack/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ad-creative-pack
-description: Generate premium paid-ad copy, creative concepts, image prompts, audience angles, and test matrices.
+description: Generate paid-ad copy, creative concepts, image prompts, audience angles, and test matrices.
+kind: instruction
 ---
 
 # Ad Creative Pack
@@ -9,29 +10,26 @@ Generate a paid-ad launch package for Meta, Google, and LinkedIn.
 
 ## Requirements
 
-- Authenticate with `skills auth login`.
-- This premium skill runs through the hosted Skills runtime; local installs expose only skill 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 ad-creative-pack "Usage-based billing for AI SaaS" --audience "founders" --goal "book demos"
-skills run ad-creative-pack --product "API monitoring" --offer "Find broken API workflows before customers do"
-```
+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 |
 |--------|-------------|---------|
-| `--product <text>` | Product, service, or campaign brief. Positional text also works. | required |
-| `--audience <text>` | Target buyer or segment. | software teams |
-| `--offer <text>` | Campaign promise or offer. | derived from product |
-| `--goal <text>` | Conversion goal. | book demos |
-| `--platforms <list>` | Comma-separated platforms. | Meta, Google, LinkedIn |
-| `--tone <tone>` | `direct`, `premium`, `friendly`, or `technical`. | direct |
-| `--output <dir>` | Output directory for direct local execution. Hosted runs use the run export directory. | run export dir |
+| `product` | Product, service, or campaign brief. Positional text also works. | required |
+| `audience` | Target buyer or segment. | software teams |
+| `offer` | Campaign promise or offer. | derived from product |
+| `goal` | Conversion goal. | book demos |
+| `platforms` | Comma-separated platforms. | Meta, Google, LinkedIn |
+| `tone` | `direct`, `premium`, `friendly`, or `technical`. | direct |
 
-## Outputs
+## Deliverables
 
 - `platform-copy.md`
 - `ad-copy.json`
@@ -42,4 +40,16 @@ skills run ad-creative-pack --product "API monitoring" --offer "Find broken API
 - `launch-checklist.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. Restate the offer, audience and platform mix in one line, and name the single
+   conversion action every asset drives toward.
+2. Draft 3-5 distinct creative concepts. Each needs a different *angle* (pain,
+   aspiration, proof, novelty, objection), not a different adjective.
+3. For each platform, write copy to that platform's real limits — headline and
+   primary text lengths differ, so do not reuse one block everywhere.
+4. Write image prompts as briefs a designer or an image model could act on:
+   subject, composition, mood, colour, text placement.
+5. Build the test matrix so exactly one variable changes per row; a matrix that
+   varies two things at once cannot attribute a win.
+6. Close with a launch checklist covering tracking, naming, and budget split.

package/skills/ad-creative-pack/package.json

@@ -5,7 +5,6 @@
   "description": "Hosted premium paid ad creative artifact generator",
   "type": "module",
   "skills": {
-    "runtime": "hosted",
-    "source": "remote"
+    "kind": "instruction"
   }
 }

package/skills/analyze-data/SKILL.md

@@ -2,7 +2,7 @@
 name: analyze-data
 version: 0.1.0
 description: Instant data science insights for CSV and JSON files with statistical summaries, quality audits, and trend detection
-author: skills.md
+author: Hasna
 category: Data & Analytics
 tags:
   - data

package/skills/analyze-data/src/formatters.ts

@@ -102,7 +102,7 @@ export function formatMarkdown(report: AnalysisReport): string {
   }
 
   md += '---\n\n';
-  md += '*Generated by skills.md/analyze-data*\n';
+  md += '*Generated by the analyze-data skill*\n';
 
   return md;
 }
@@ -225,7 +225,7 @@ export function formatHTML(report: AnalysisReport): string {
         ` : ''}
 
         <footer>
-            Generated by <strong>skills.md/analyze-data</strong>
+            Generated by <strong>the analyze-data skill</strong>
         </footer>
     </div>
 </body>

package/skills/api-docs-portal/SKILL.md

@@ -1,46 +1,84 @@
 ---
 name: api-docs-portal
-description: Generate premium API documentation portals from OpenAPI specs, route lists, or examples.
+description: Generate a self-contained static API documentation portal, normalized endpoint JSON, and a markdown reference from an OpenAPI 3.x or Swagger 2.0 spec.
 ---
 
 # API Docs Portal
 
-Generate a polished API documentation portal from OpenAPI specs, route files, or endpoint examples.
+Turn an OpenAPI/Swagger document into a browsable static portal. Everything is
+generated locally and deterministically: no network calls, no credentials, and
+the emitted HTML makes no external requests.
+
+## What It Does
+
+- Reads OpenAPI 3.x or Swagger 2.0 specs in JSON or YAML.
+- Resolves local `$ref` pointers (`#/components/schemas/...`, `#/definitions/...`) with a cycle guard, so referenced request/response schemas render inline.
+- Groups endpoints by their first tag, falling back to the first path segment.
+- Renders method, path, summary, description, deprecation, path/query/header/cookie parameters (including path-level shared parameters), request body fields, and per-status response fields.
+- Flattens nested object schemas up to three levels and labels types (`string<uuid>`, `object[]`, `string (open | paid | cancelled)`, `A | B`).
+- Extracts security schemes and per-operation security requirements, and generates a cURL example per endpoint.
 
 ## 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.x
+- npm dependency: `yaml` (install once with `bun install` in this skill directory) — only needed for YAML specs, JSON specs parse natively
+- An OpenAPI/Swagger document with a `paths` object. External (`http://`, `other.yaml#/...`) `$ref`s are not fetched; they are marked as unresolved in the output.
 
 ## Usage
 
 ```bash
-skills run api-docs-portal --spec "GET /v1/projects, POST /v1/projects" --title "Acme API"
-skills run api-docs-portal --spec-file ./openapi.json --base-url "https://api.example.com" --auth bearer
+# Generate the portal into ./api-portal
+skills run api-docs-portal -- --spec ./openapi.yaml
+
+# Dark theme, custom output directory and base URL
+skills run api-docs-portal -- --spec ./openapi.json --output ./docs/api \
+  --theme slate --base-url https://api.example.com/v2
+
+# Machine-readable summary on stdout
+skills run api-docs-portal -- --spec ./openapi.yaml --json
 ```
 
+Then open `./api-portal/index.html` in a browser. Run it directly from the skill
+directory with `bun run src/index.ts --spec ./openapi.yaml`.
+
 ## Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--spec <text>` | OpenAPI JSON, route list, or endpoint examples. Positional text also works. | required |
-| `--spec-file <path>` | Read the API spec or route list from a file. | none |
-| `--title <text>` | Portal and API title. | API Documentation |
-| `--base-url <url>` | Base URL used in examples. | https://api.example.com |
-| `--auth <mode>` | Auth mode: `bearer`, `api-key`, `oauth`, `session`, or `none`. | bearer |
-| `--theme <name>` | Portal theme: `light` or `slate`. | light |
-| `--output <dir>` | Output directory for direct local execution. Hosted runs use the run export directory. | run export dir |
+| `-s, --spec <path>` | OpenAPI/Swagger document, JSON or YAML (also accepted positionally) | required |
+| `-o, --output <dir>` | Output directory | `./api-portal` |
+| `--theme <name>` | `light` or `slate` | `light` |
+| `--base-url <url>` | Base URL shown in the portal and cURL examples | first `servers[].url` |
+| `--title <text>` | Override the portal title | spec `info.title` |
+| `--json` | Print a JSON summary on stdout | off |
+| `--help` | Show usage | |
+| `--version` | Show version | |
 
 ## Outputs
 
-- `site/index.html`
-- `site/styles.css`
-- `site/endpoints.json`
-- `openapi.json`
-- `endpoint-reference.md`
-- `auth-guide.md`
-- `examples.md`
-- `README.md`
-- `manifest.json`
-
-After submitting a hosted run, poll with `skills runs status <run-id>` and download outputs with `skills exports download <run-id>`.
+Written into `--output` (default `./api-portal`):
+
+| File | Contents |
+|------|----------|
+| `index.html` | Self-contained portal: inline CSS, sticky sidebar navigation, responsive layout, zero external requests (no CDN scripts, fonts, or images) |
+| `endpoints.json` | Normalized endpoint model (method, path, group, params, request body fields, response fields, security) |
+| `reference.md` | Markdown API reference with parameter/field tables and cURL examples |
+
+Without `--json`, a summary is printed to stdout:
+
+```
+api-docs-portal: /abs/path/openapi.yaml
+  title      Orders API v2.1.0
+  base url   https://api.example.com/v2
+  theme      slate
+  endpoints  5 in 2 groups
+    customers: 1
+    orders: 4
+  output     /abs/path/api-portal
+  files      index.html, endpoints.json, reference.md
+```
+
+## Exit Codes
+
+- `0` — portal generated
+- `1` — missing/unreadable spec, invalid JSON/YAML, no `paths` object, no operations, or an invalid option value

package/skills/api-docs-portal/package.json

@@ -2,10 +2,34 @@
   "name": "api-docs-portal",
   "version": "0.1.0",
   "private": true,
-  "description": "Hosted skill metadata for api-docs-portal",
+  "description": "Generate a self-contained static API documentation portal from an OpenAPI or Swagger spec",
   "type": "module",
-  "skills": {
-    "runtime": "hosted",
-    "source": "remote"
+  "main": "src/index.ts",
+  "bin": {
+    "api-docs-portal": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "openapi",
+    "swagger",
+    "documentation",
+    "static-site",
+    "cli",
+    "skill"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
   }
 }