4-skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheng Suk Huang
+
+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,36 @@
+# 4-skill
+
+Three portable AI agent skills for VS Code Copilot Agent mode:
+
+- `repo-map` creates an evidence-based repository map.
+- `source-scout` creates a cited technical decision brief.
+- `delivery-plan` turns a request into an implementation-ready plan.
+
+## Install
+
+From a project folder:
+
+```bash
+npx 4-skill@latest init
+```
+
+This creates:
+
+```text
+.github/skills/
+├── repo-map/SKILL.md
+├── source-scout/SKILL.md
+└── delivery-plan/SKILL.md
+```
+
+Existing skill files are preserved. Use `npx 4-skill@latest init --force` to replace them.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run pack:check
+```
+
+Publishing is configured in GitHub Actions on pushes to `main`. Configure npm Trusted Publishing for this repository before the first release.

package/bin/4-skill.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,39 @@
+{
+  "name": "4-skill",
+  "version": "0.1.0",
+  "description": "Three practical AI agent skills for repository understanding, research, and delivery planning",
+  "type": "module",
+  "bin": {
+    "4-skill": "bin/4-skill.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SukHuang/4_skill.git"
+  },
+  "homepage": "https://github.com/SukHuang/4_skill",
+  "bugs": {
+    "url": "https://github.com/SukHuang/4_skill/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "skills",
+    "copilot",
+    "developer-tools"
+  ],
+  "license": "MIT"
+}

package/skills/delivery-plan/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: delivery-plan
+description: Turn a product or engineering request into a small, verifiable implementation plan.
+---
+
+# Delivery Plan
+
+Use this skill when an idea, bug report, or feature request needs to become executable engineering work.
+
+## Method
+
+1. Restate the desired outcome and identify the user or system affected.
+2. Inspect the relevant repository surfaces before proposing files or APIs.
+3. Separate explicit requirements, assumptions, non-goals, and unresolved choices.
+4. Break the work into ordered slices that can each be implemented and checked.
+5. Write `DELIVERY_PLAN.md` unless another output path is requested.
+
+## Include
+
+- Problem statement and goals
+- Assumptions and non-goals
+- Proposed behavior and technical approach
+- Ordered tasks with likely files or modules
+- Acceptance criteria
+- Focused test strategy
+- Risks, rollback considerations, and open questions
+
+Do not silently decide between materially different product behaviors. Make the smallest useful plan that still gives an implementer a clear validation path.

package/skills/repo-map/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: repo-map
+description: Build an evidence-based map of a software repository for onboarding or focused investigation.
+---
+
+# Repository Map
+
+Use this skill when someone needs to understand an unfamiliar repository or locate the right implementation surface.
+
+## Method
+
+1. Inspect the top-level tree, manifests, configuration, documentation, entry points, and tests.
+2. Follow one representative execution path from its entry point through the main modules.
+3. Verify commands and claims against files; label anything that could not be confirmed.
+4. Write `REPOSITORY_MAP.md` unless another output path is requested.
+
+## Include
+
+- Purpose and key user-facing flows
+- Architecture and one concrete data or control-flow path
+- Important directories and files
+- Install, development, test, and build commands
+- Configuration, external services, and environment variables
+- Risks, unknowns, and useful next steps
+
+Keep the result concise and operational. Never invent behavior, dependencies, or files.

package/skills/source-scout/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: source-scout
+description: Investigate a technical question using authoritative sources and produce a traceable decision brief.
+---
+
+# Source Scout
+
+Use this skill to compare tools, investigate a technical claim, or prepare a recommendation that depends on external evidence.
+
+## Method
+
+1. Define the decision, constraints, and questions that must be answered.
+2. Start with user-provided links, official documentation, specifications, and primary sources.
+3. Record the source for every material claim and distinguish facts from interpretation.
+4. Prefer current sources; state the access date when available.
+5. Write `DECISION_BRIEF.md` unless another output path is requested.
+
+## Include
+
+- Decision summary
+- Findings grouped by question
+- Comparison and trade-offs
+- Recommendation tied to the stated constraints
+- Sources with inline links
+- Unresolved questions and verification steps
+
+Do not imply that a source was consulted when it was not. Do not turn a weak source into certainty through confident wording.

package/src/cli.js

@@ -0,0 +1,33 @@
+import { installSkills } from "./install-skills.js";
+
+const HELP = `4-skill - install practical AI agent skills
+
+Usage:
+  4-skill init [--force]
+
+Commands:
+  init [--force]  Install the three skills in .github/skills
+
+Installed skills:
+  repo-map        Map a repository for onboarding or investigation
+  source-scout    Research a technical decision with traceable sources
+  delivery-plan   Turn a request into verifiable engineering work
+
+Options:
+  --help          Show this help
+`;
+
+export async function run(args) {
+  const [command, ...options] = args;
+
+  if (!command || command === "--help" || command === "-h") {
+    console.log(HELP);
+    return;
+  }
+
+  if (command === "init") {
+    return installSkills({ force: options.includes("--force") });
+  }
+
+  throw new Error(`Unknown command "${command}". Run "4-skill --help" for usage.`);
+}

package/src/install-skills.js

@@ -0,0 +1,39 @@
+import { cp, mkdir, readdir, readFile, writeFile } 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");
+
+export async function installSkills({ force = false } = {}) {
+  const targetRoot = path.join(process.cwd(), ".github", "skills");
+  const skillNames = await readdir(sourceRoot, { withFileTypes: true });
+  const installed = [];
+
+  for (const entry of skillNames) {
+    if (!entry.isDirectory()) continue;
+
+    const sourceFile = path.join(sourceRoot, entry.name, "SKILL.md");
+    const targetDirectory = path.join(targetRoot, entry.name);
+    const targetFile = path.join(targetDirectory, "SKILL.md");
+
+    if (!force) {
+      try {
+        await readFile(targetFile);
+        continue;
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+
+    await mkdir(targetDirectory, { recursive: true });
+    await cp(sourceFile, targetFile, { force: true });
+    installed.push(entry.name);
+  }
+
+  if (installed.length === 0) {
+    console.log("No skills installed. Existing files were preserved; use --force to replace them.");
+  } else {
+    console.log(`Installed ${installed.length} skill${installed.length === 1 ? "" : "s"}: ${installed.join(", ")}`);
+  }
+}