@ianyian/myskills 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,9 @@
 # @ianyian/myskills
 
-Three practical AI skills that turn a Node.js CLI into a small project assistant:
+Three portable VS Code Agent Skills that turn an AI coding agent 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.
+- **`repo-explorer`** understands a local repository and creates an architecture and onboarding guide.
+- **`research-brief`** researches a topic and creates a cited Markdown brief.
 - **`idea-to-execution`** converts an idea into an implementation plan with tasks and acceptance criteria.
 
 Repository: <https://github.com/ianyian/mySKILLs>
@@ -11,9 +11,9 @@ Repository: <https://github.com/ianyian/mySKILLs>
 ## Requirements
 
 - Node.js 18 or newer
-- An OpenAI-compatible API key
+- VS Code with GitHub Copilot Agent mode, or another agent that supports `.github/skills/*/SKILL.md`
 
-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`.
+The default workflow does not require an API key. VS Code Copilot supplies the model and executes the skills.
 
 ## Install and configure
 
@@ -29,50 +29,56 @@ Or install globally:
 npm install --global @ianyian/myskills
 ```
 
-Configure the model client:
+Install the skills into the project you have open in VS Code:
 
 ```bash
-export OPENAI_API_KEY="your-api-key"
-# Optional:
-export OPENAI_MODEL="gpt-4o-mini"
-export OPENAI_BASE_URL="https://api.openai.com/v1"
+npx @ianyian/myskills@latest init
 ```
 
-## Examples
+This creates:
 
-Analyze the current repository:
+```text
+.github/skills/
+├── repo-explorer/SKILL.md
+├── research-brief/SKILL.md
+└── idea-to-execution/SKILL.md
+```
+
+Restart or reload the VS Code window if the agent does not discover the skills immediately. Use `--force` only when you want to replace existing skill files:
 
 ```bash
-npx @ianyian/myskills repo-explorer .
+npx @ianyian/myskills@latest init --force
 ```
 
-This creates `PROJECT_OVERVIEW.md`. Choose another output path with `--output`:
+## Use the skills with VS Code Agent mode
+
+Open the project in VS Code, start GitHub Copilot Chat in Agent mode, and ask naturally:
+
+Analyze the current repository:
 
 ```bash
-npx @ianyian/myskills repo-explorer ./my-project --output docs/onboarding.md
+Create a repository onboarding guide using the repo-explorer skill.
 ```
 
-Create a research brief:
+This creates `PROJECT_OVERVIEW.md`. Other examples:
 
 ```bash
-npx @ianyian/myskills research-brief "Compare PostgreSQL and MongoDB"
+Use the research-brief skill to compare PostgreSQL and MongoDB, with citations.
 ```
 
-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
+Use the idea-to-execution skill to plan dark mode for this web application.
 ```
 
-Turn a product idea into an execution plan:
+The agent reads each `SKILL.md`, inspects the project or web sources as needed, and creates the requested artifact.
+
+## Optional standalone CLI mode
+
+The original commands remain available for users who want this package to call an OpenAI-compatible model directly. This mode requires `OPENAI_API_KEY`:
 
 ```bash
-npx @ianyian/myskills idea-to-execution \
-  "Add dark mode to my web application" \
-  --output implementation-plan.md
+export OPENAI_API_KEY="your-api-key"
+npx @ianyian/myskills repo-explorer .
 ```
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ianyian/myskills",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Practical AI skills for repository analysis, research, and execution planning",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bin",
+    "skills",
     "src",
     "README.md",
     "LICENSE"

package/skills/idea-to-execution/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: idea-to-execution
+description: Turn a product or engineering idea into an implementation-ready plan.
+---
+
+# Idea to Execution
+
+Use this skill when the user has a rough idea and wants an actionable engineering plan.
+
+## Workflow
+
+1. Restate the problem and intended outcome.
+2. Make assumptions explicit and identify non-goals.
+3. Inspect the repository when the idea relates to an existing codebase.
+4. Produce `implementation-plan.md` unless the user requests another output path.
+5. Include:
+   - Problem and goals
+   - User experience
+   - Proposed technical approach
+   - Ordered tasks with likely files or modules
+   - Acceptance criteria
+   - Testing strategy
+   - Risks and open questions
+
+Keep tasks small enough to implement and verify independently. Do not silently make product decisions when multiple reasonable options exist.

package/skills/repo-explorer/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: repo-explorer
+description: Understand a repository and create a practical architecture and onboarding guide.
+---
+
+# Repository Explorer
+
+Use this skill when the user asks you to understand, document, or onboard someone to a repository.
+
+## Workflow
+
+1. Inspect the repository structure, package manifests, configuration, entry points, tests, and documentation.
+2. Trace the main execution or data flow. Prefer evidence from source code over assumptions.
+3. Identify the commands needed to install, run, test, and build the project.
+4. Write `PROJECT_OVERVIEW.md` unless the user requests another output path.
+5. Include:
+   - Executive summary
+   - Architecture and data flow
+   - Important directories and files
+   - Setup and development commands
+   - Dependencies and configuration
+   - Risks, unknowns, and recommended next steps
+
+Do not invent behavior or claim that a file exists without inspecting it. Keep the guide concise enough to be useful during onboarding.

package/skills/research-brief/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: research-brief
+description: Research a topic using available web tools and produce a concise cited Markdown brief.
+---
+
+# Research Brief
+
+Use this skill when the user asks to compare technologies, investigate a topic, or summarize external information.
+
+## Workflow
+
+1. Clarify the scope and the decision the research should support.
+2. Prefer primary and authoritative sources. Use the user's URLs when supplied.
+3. Separate verified facts, expert recommendations, and interpretation.
+4. Produce `research-brief.md` unless the user requests another output path.
+5. Include:
+   - Executive summary
+   - Key findings
+   - Comparison and trade-offs where relevant
+   - Practical recommendation
+   - Sources with inline citations
+   - Open questions or claims requiring verification
+
+Do not imply that a source was consulted if it was not. Include access dates when the agent's available tooling supports them.

package/src/cli.js

@@ -1,6 +1,7 @@
 import { runRepoExplorer } from "./skills/repo-explorer.js";
 import { runResearchBrief } from "./skills/research-brief.js";
 import { runIdeaToExecution } from "./skills/idea-to-execution.js";
+import { installSkills } from "./install-skills.js";
 
 const HELP = `@ianyian/myskills - practical AI skills for projects
 
@@ -11,6 +12,7 @@ Commands:
   repo-explorer [directory]       Analyze a repository
   research-brief <topic>         Create a research brief
   idea-to-execution <idea>        Create an implementation plan
+  init [--force]                  Install VS Code Agent Skills in this project
 
 Options:
   --output <file>                 Output Markdown path
@@ -32,5 +34,6 @@ export async function run(args) {
   if (command === "repo-explorer") return runRepoExplorer(rest);
   if (command === "research-brief") return runResearchBrief(rest);
   if (command === "idea-to-execution") return runIdeaToExecution(rest);
+  if (command === "init") return installSkills({ force: rest.includes("--force") });
   throw new Error(`Unknown command "${command}". Run "myskills --help" for usage.`);
 }

package/src/install-skills.js

@@ -0,0 +1,29 @@
+import { access, cp, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourceRoot = path.join(packageRoot, "skills");
+
+const skillNames = ["repo-explorer", "research-brief", "idea-to-execution"];
+
+export async function installSkills({ force = false } = {}) {
+  const destinationRoot = path.resolve(".github", "skills");
+  await mkdir(destinationRoot, { recursive: true });
+
+  for (const skillName of skillNames) {
+    const source = path.join(sourceRoot, skillName);
+    const destination = path.join(destinationRoot, skillName);
+    if (!force) {
+      try {
+        await access(destination);
+        throw new Error(`${destination} already exists. Use --force to replace it.`);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    await cp(source, destination, { recursive: true, force });
+  }
+
+  console.log(`Installed ${skillNames.length} VS Code Agent Skills in ${destinationRoot}`);
+}