@ianyian/myskills 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,101 @@
+# @ianyian/myskills
+
+Three practical AI skills that turn a Node.js CLI into a small project assistant:
+
+- **`repo-explorer`** understands a local repository and writes an architecture and onboarding guide.
+- **`research-brief`** turns a topic and optional URLs into a cited Markdown research brief.
+- **`idea-to-execution`** converts an idea into an implementation plan with tasks and acceptance criteria.
+
+Repository: <https://github.com/ianyian/mySKILLs>
+
+## Requirements
+
+- Node.js 18 or newer
+- An OpenAI-compatible API key
+
+The CLI uses the OpenAI-compatible Chat Completions API. It works with OpenAI by default and can be pointed at another compatible provider with `OPENAI_BASE_URL`.
+
+## Install and configure
+
+Run without installing:
+
+```bash
+npx @ianyian/myskills --help
+```
+
+Or install globally:
+
+```bash
+npm install --global @ianyian/myskills
+```
+
+Configure the model client:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+# Optional:
+export OPENAI_MODEL="gpt-4o-mini"
+export OPENAI_BASE_URL="https://api.openai.com/v1"
+```
+
+## Examples
+
+Analyze the current repository:
+
+```bash
+npx @ianyian/myskills repo-explorer .
+```
+
+This creates `PROJECT_OVERVIEW.md`. Choose another output path with `--output`:
+
+```bash
+npx @ianyian/myskills repo-explorer ./my-project --output docs/onboarding.md
+```
+
+Create a research brief:
+
+```bash
+npx @ianyian/myskills research-brief "Compare PostgreSQL and MongoDB"
+```
+
+Add source URLs. The skill fetches their text and asks the model to cite them:
+
+```bash
+npx @ianyian/myskills research-brief \
+  "Best practices for Node.js error handling" \
+  --url https://nodejs.org/en/learn/getting-started/introduction-to-nodejs \
+  --output docs/node-research.md
+```
+
+Turn a product idea into an execution plan:
+
+```bash
+npx @ianyian/myskills idea-to-execution \
+  "Add dark mode to my web application" \
+  --output implementation-plan.md
+```
+
+## Development
+
+```bash
+npm install
+npm test
+npm pack --dry-run
+```
+
+The package contains no runtime dependencies; it uses Node.js built-ins and `fetch`.
+
+## Publish
+
+After logging in to npm, publish a new version:
+
+```bash
+npm login
+npm publish --access public
+```
+
+Every later publish needs a new version, for example `npm version patch && npm publish`.
+
+## Security and privacy
+
+The CLI sends the repository excerpts or fetched source text to the configured model provider. Review your provider's data policy before using it with private code. API keys are read from environment variables and are never written to generated files.

package/bin/myskills.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { run } from "../src/cli.js";
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@ianyian/myskills",
+  "version": "0.1.0",
+  "description": "Practical AI skills for repository analysis, research, and execution planning",
+  "type": "module",
+  "bin": {
+    "myskills": "bin/myskills.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "start": "node ./bin/myskills.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ianyian/mySKILLs.git"
+  },
+  "homepage": "https://github.com/ianyian/mySKILLs",
+  "bugs": {
+    "url": "https://github.com/ianyian/mySKILLs/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "cli",
+    "automation"
+  ],
+  "license": "MIT"
+}

package/src/cli.js

@@ -0,0 +1,36 @@
+import { runRepoExplorer } from "./skills/repo-explorer.js";
+import { runResearchBrief } from "./skills/research-brief.js";
+import { runIdeaToExecution } from "./skills/idea-to-execution.js";
+
+const HELP = `@ianyian/myskills - practical AI skills for projects
+
+Usage:
+  myskills <command> [arguments] [options]
+
+Commands:
+  repo-explorer [directory]       Analyze a repository
+  research-brief <topic>         Create a research brief
+  idea-to-execution <idea>        Create an implementation plan
+
+Options:
+  --output <file>                 Output Markdown path
+  --url <url>                     Source URL (repeatable, research-brief only)
+  --help                          Show this help
+
+Environment:
+  OPENAI_API_KEY                  Required model provider API key
+  OPENAI_MODEL                    Optional model (default: gpt-4o-mini)
+  OPENAI_BASE_URL                 Optional OpenAI-compatible API base URL`;
+
+export async function run(args) {
+  const [command, ...rest] = args;
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  if (command === "repo-explorer") return runRepoExplorer(rest);
+  if (command === "research-brief") return runResearchBrief(rest);
+  if (command === "idea-to-execution") return runIdeaToExecution(rest);
+  throw new Error(`Unknown command "${command}". Run "myskills --help" for usage.`);
+}

package/src/model-client.js

@@ -0,0 +1,38 @@
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_MODEL = "gpt-4o-mini";
+
+export async function complete({ system, user }) {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) {
+    throw new Error("OPENAI_API_KEY is not set. Export an OpenAI-compatible API key and try again.");
+  }
+
+  const baseUrl = (process.env.OPENAI_BASE_URL || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: process.env.OPENAI_MODEL || DEFAULT_MODEL,
+      temperature: 0.2,
+      messages: [
+        { role: "system", content: system },
+        { role: "user", content: user },
+      ],
+    }),
+  });
+
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const detail = body?.error?.message || response.statusText;
+    throw new Error(`Model request failed (${response.status}): ${detail}`);
+  }
+
+  const content = body?.choices?.[0]?.message?.content;
+  if (typeof content !== "string" || content.trim() === "") {
+    throw new Error("Model response did not contain text.");
+  }
+  return content.trim();
+}

package/src/shared.js

@@ -0,0 +1,31 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function writeOutput(filePath, content) {
+  const absolutePath = path.resolve(filePath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, `${content.trim()}\n`, "utf8");
+  return absolutePath;
+}
+
+export function optionValue(args, name, fallback) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+export function optionValues(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === name && args[index + 1]) values.push(args[index + 1]);
+  }
+  return values;
+}
+
+export function removeOptions(args, names) {
+  const result = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (names.includes(args[index])) index += 1;
+    else result.push(args[index]);
+  }
+  return result;
+}

package/src/skills/idea-to-execution.js

@@ -0,0 +1,27 @@
+import { complete } from "../model-client.js";
+import { optionValue, removeOptions, writeOutput } from "../shared.js";
+
+export async function runIdeaToExecution(args) {
+  const output = optionValue(args, "--output", "implementation-plan.md");
+  const idea = removeOptions(args, ["--output"]).join(" ").trim();
+  if (!idea) throw new Error("Provide an idea to turn into an execution plan.");
+
+  const result = await complete({
+    system: "You are a pragmatic technical product manager and software architect. Make assumptions explicit and keep the plan implementable.",
+    user: `Turn this idea into an execution-ready Markdown plan:
+
+${idea}
+
+Include:
+1. Problem and goals
+2. Assumptions and non-goals
+3. Proposed user experience
+4. Technical approach
+5. Ordered implementation tasks with likely files or modules
+6. Acceptance criteria
+7. Testing strategy
+8. Risks and open questions`,
+  });
+  const written = await writeOutput(output, result);
+  console.log(`Implementation plan written to ${written}`);
+}

package/src/skills/repo-explorer.js

@@ -0,0 +1,57 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { complete } from "../model-client.js";
+import { optionValue, writeOutput } from "../shared.js";
+
+const IGNORED = new Set([".git", "node_modules", "dist", "build", "coverage", ".next"]);
+const MAX_FILES = 80;
+const MAX_CHARS_PER_FILE = 5000;
+
+async function collectFiles(directory, relative = "") {
+  if (relative.split(path.sep).some((part) => IGNORED.has(part))) return [];
+  const entries = await readdir(path.join(directory, relative), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...await collectFiles(directory, child));
+    else if (files.length < MAX_FILES && !entry.name.startsWith(".env")) files.push(child);
+    if (files.length >= MAX_FILES) break;
+  }
+  return files;
+}
+
+export async function runRepoExplorer(args) {
+  const directory = args[0] && !args[0].startsWith("--") ? args[0] : ".";
+  const output = optionValue(args, "--output", "PROJECT_OVERVIEW.md");
+  const root = path.resolve(directory);
+  if (!(await stat(root)).isDirectory()) throw new Error(`${directory} is not a directory.`);
+
+  const files = await collectFiles(root);
+  const excerpts = [];
+  for (const relative of files) {
+    try {
+      const content = await readFile(path.join(root, relative), "utf8");
+      excerpts.push(`### ${relative}\n${content.slice(0, MAX_CHARS_PER_FILE)}`);
+    } catch {
+      // Binary and unreadable files are represented by the file list only.
+      excerpts.push(`### ${relative}\n[content unavailable]`);
+    }
+  }
+
+  const result = await complete({
+    system: "You are a senior software architect. Produce accurate, practical Markdown. Do not invent files, dependencies, or behavior that is not supported by the supplied repository evidence.",
+    user: `Analyze this repository and write an onboarding document with these sections:
+1. Executive summary
+2. Architecture and data flow
+3. Important directories and files
+4. How to run, test, and extend it
+5. Dependencies and configuration
+6. Risks, unknowns, and recommended next steps
+
+Repository: ${root}
+File excerpts:
+${excerpts.join("\n\n")}`,
+  });
+  const written = await writeOutput(output, result);
+  console.log(`Repository overview written to ${written}`);
+}

package/src/skills/research-brief.js

@@ -0,0 +1,33 @@
+import { complete } from "../model-client.js";
+import { optionValue, optionValues, removeOptions, writeOutput } from "../shared.js";
+
+export async function runResearchBrief(args) {
+  const urls = optionValues(args, "--url");
+  const output = optionValue(args, "--output", "research-brief.md");
+  const topicArgs = removeOptions(args, ["--url", "--output"]);
+  const topic = topicArgs.join(" ").trim();
+  if (!topic) throw new Error("Provide a research topic.");
+
+  const sources = [];
+  for (const url of urls) {
+    let response;
+    try {
+      response = await fetch(url);
+    } catch (error) {
+      throw new Error(`Could not fetch ${url}: ${error.message}`);
+    }
+    if (!response.ok) throw new Error(`Could not fetch ${url} (${response.status}).`);
+    sources.push(`SOURCE: ${url}\n${(await response.text()).slice(0, 12000)}`);
+  }
+
+  const result = await complete({
+    system: "You are a careful research analyst. Distinguish facts from interpretation, cite supplied URLs inline as [1], [2], and never claim to have consulted sources that were not supplied.",
+    user: `Create a concise Markdown research brief about: ${topic}
+
+Include: an executive summary, key findings, comparison or trade-offs where relevant, practical recommendations, and a Sources section. If no URLs are supplied, clearly label claims that need verification.
+
+${sources.length ? sources.join("\n\n") : "No source URLs were supplied."}`,
+  });
+  const written = await writeOutput(output, result);
+  console.log(`Research brief written to ${written}`);
+}