@daldindev/agentic-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-03
+
+### Added
+
+- `agentic-skills` CLI with `init`, `update`, and `status`.
+- `init` and `update` download the current [ag-kit](https://github.com/vudovn/ag-kit) archive from GitHub and install its agent roles, skills, and workflows, plus the upstream license.
+- `ARCHITECTURE.md` installed with only the sections that describe the installed content, falling back to the verbatim file with a warning if upstream renames a section.
+- Hash manifest in `.agentic-skills/manifest.json` recording the upstream commit and version, so updates preserve locally modified files and never touch user-created ones.
+- `--ref` to install a specific upstream branch, tag, or commit, and `--archive` to install from a local tarball or URL.
+- `--path`, `--dir`, `--force`, `--dry-run`, and `--json` options.
+- Archives are read as untrusted input: entries that would escape the target directory are rejected, downloads time out, and decompression is capped.

package/LICENSE

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

@@ -0,0 +1,11 @@
+# Notice
+
+`agentic-skills` is an installer. It contains no content of its own.
+
+When you run it, it downloads the current source archive of the **ag-kit** project (<https://github.com/vudovn/ag-kit>) by **VUDOVN**, licensed under the MIT License, and writes that project's agent roles, skills, and workflows into your project. The upstream license file is written next to them as `LICENSE`, so every installed copy carries the original copyright notice.
+
+Everything installed is upstream work, copied byte for byte, with one exception: `ARCHITECTURE.md` is assembled from the upstream inventory by keeping whole sections and dropping the ones about tooling that this installer does not set up. The sections that remain are upstream text, unchanged.
+
+This project is independent. It is not affiliated with, endorsed by, or maintained by the ag-kit project or by the IDE runtime that project targets. Problems with the content belong upstream; problems with the installer belong here.
+
+The installer itself, this repository, and its documentation are © 2026 daldindev, released under the MIT License in [LICENSE](LICENSE).

package/README.md

@@ -0,0 +1,143 @@
+# agentic-skills
+
+Install the [ag-kit](https://github.com/vudovn/ag-kit) **agent roles, skills, and workflows** into any project, for any model and any agent harness.
+
+## Why it exists
+
+ag-kit is a large, well-organized body of agent instructions: 20 specialist roles, 47 skills, 13 workflows. Upstream delivers it as a workspace for one IDE runtime, so using any of it means adopting that runtime and the contract it comes with.
+
+This installer removes that condition. One command downloads the current ag-kit and writes only the instructions into your project, as plain Markdown that whatever assistant you already use can read:
+
+- The upstream roles, skills, and workflows, **verbatim** and always current, because every install reads upstream directly.
+- One command to install, one to update, with local edits **preserved**.
+- The exact upstream commit recorded with every install.
+- **No runtime dependencies**, and no `git` needed on your machine.
+
+Everything else upstream ships sits around that content to bind it to that one runtime: hooks, an MCP configuration, the memory and rule loading, schemas, manifests, and validators. A portable install has no use for wiring, so none of it is installed.
+
+## Install
+
+```bash
+npx @daldindev/agentic-skills init
+```
+
+Or add it to the project so the installer version is pinned in `package.json`:
+
+```bash
+npm i -D @daldindev/agentic-skills
+npx agentic-skills init
+```
+
+Requirements:
+
+- Node.js `>=20.11`
+- Network access to `codeload.github.com`, where GitHub serves source archives, when you run `init` or `update`
+
+## Quick Start
+
+`init` creates `.agents/` in the current project:
+
+```plaintext
+.agents/
+├── ARCHITECTURE.md                 # Inventory of every agent, skill, and workflow
+├── LICENSE                         # Upstream MIT license
+├── agent/                          # 20 role definitions
+├── skills/                         # 47 skills, each a folder with a SKILL.md
+├── workflows/                      # 13 slash-command procedures
+└── .agentic-skills/manifest.json   # File hashes and the upstream commit, so updates can protect your edits
+```
+
+Point your assistant at `.agents/ARCHITECTURE.md`. It lists every component with a one-line purpose, so the assistant can open only what a task needs.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `agentic-skills init` | Download ag-kit and install the content. Refuses a non-empty target unless `--force` |
+| `agentic-skills update` | Download ag-kit again and update installed files, keeping the ones you edited |
+| `agentic-skills status` | Show what is installed, from which upstream commit, and which files were changed locally |
+
+| Option | Purpose |
+| --- | --- |
+| `-p, --path <dir>` | Project directory, default is the current directory |
+| `-d, --dir <name>` | Install directory inside the project, default `.agents` |
+| `-r, --ref <git-ref>` | Upstream branch, tag, or commit to install, default `main` |
+| `--archive <source>` | Install from a local ag-kit `.tar.gz` or a URL instead of GitHub |
+| `-f, --force` | Overwrite files that were modified locally |
+| `--dry-run` | Download and print the plan without writing anything |
+| `--json` | Print machine-readable output |
+
+Exit code `2` means the command succeeded but skipped files you had modified. They are listed in the output.
+
+## Updating
+
+There is nothing to bump. `update` downloads the current upstream and applies it:
+
+```bash
+npx @daldindev/agentic-skills update
+```
+
+For each file it compares what is installed, what upstream now has, and the hash recorded at the last run.
+
+| Situation | Result |
+| --- | --- |
+| You never touched the file | Updated, or deleted when upstream dropped it |
+| You edited the file | Skipped and listed, unless `--force` |
+| You created the file yourself | Never touched |
+| Upstream added a file | Installed |
+
+To stay on a known upstream state instead of `main`, pass a tag or commit. The same flag reproduces an earlier install exactly:
+
+```bash
+npx @daldindev/agentic-skills update --ref v2026.8.31
+```
+
+## What gets installed
+
+| Upstream path | Installed as |
+| --- | --- |
+| `.agents/agent/` | `agent/` |
+| `.agents/skills/` | `skills/` |
+| `.agents/workflows/` | `workflows/` |
+| `.agents/ARCHITECTURE.md` | `ARCHITECTURE.md`, see below |
+| `LICENSE` | `LICENSE` |
+
+Files are copied byte for byte from the upstream archive at the moment you run the command. Nothing is rewritten, summarized, or adapted, and the commit they came from goes into the manifest.
+
+`ARCHITECTURE.md` is the one exception. Upstream's inventory also documents its own runtime tooling, so the installer keeps the sections that describe the installed content (**Agents**, **Skills**, **Workflows**, **Skill Loading Protocol**, **Quick Reference**) and drops the rest. Whole sections only, never edited lines. If upstream ever renames one of those sections, the file is installed verbatim and a warning is printed, so an upstream change can never block an install.
+
+Some installed files still mention the upstream runtime or its folders in passing. Ignore those references, or point them at your own equivalent.
+
+The archive is treated as untrusted input, and nothing in it is ever executed. See [`SECURITY.md`](./SECURITY.md) for what that means in practice.
+
+## Using the Content
+
+The content is deliberately tool-neutral:
+
+- **Agents** are Markdown files with YAML frontmatter (`name`, `description`, `tools`, `skills`). Use them as system prompts or subagent definitions.
+- **Skills** are folders whose `SKILL.md` frontmatter includes `when_to_use`, so an assistant can decide when to load one. Some ship Python helper scripts.
+- **Workflows** are slash-command procedures, where `$ARGUMENTS` stands for the text after the command.
+
+Keep the install at `.agents/` when you can, because paths inside the content are written relative to that folder. If your tool expects its own layout, copy or link the pieces it needs and still point it at `ARCHITECTURE.md` as the entry point.
+
+## Scope and Non-Goals
+
+In scope:
+
+- Downloading the upstream roles, skills, and workflows and installing them anywhere
+- Updating an install while preserving local edits
+- Recording upstream provenance with every install
+
+Out of scope:
+
+- Authoring, editing, or hosting the content, which lives upstream and only upstream
+- Rebuilding upstream's runtime wiring, which a portable install does not need
+- Any dependency on a specific IDE, model, or agent runtime
+
+## Contributing
+
+The installer is small on purpose. Issues and pull requests are welcome for the installer itself; problems with an agent, skill, or workflow belong upstream in ag-kit. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for local checks and release validation.
+
+## License
+
+MIT. The installed content is © VUDOVN under the MIT License and carries its own `LICENSE` file. See [`NOTICE.md`](./NOTICE.md).

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@daldindev/agentic-skills",
+  "version": "0.1.0",
+  "description": "Install the ag-kit agent roles, skills, and workflows into any project, for any model and any agent harness.",
+  "author": "daldindev",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "bin": {
+    "agentic-skills": "src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "ai",
+    "agents",
+    "agent-skills",
+    "skills",
+    "workflows",
+    "prompts",
+    "cli",
+    "installer",
+    "ag-kit"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daldindev/agentic-skills.git"
+  },
+  "bugs": {
+    "url": "https://github.com/daldindev/agentic-skills/issues"
+  },
+  "homepage": "https://github.com/daldindev/agentic-skills#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "test": "node tests/run.mjs",
+    "check": "npm run lint && npm test",
+    "pack:check": "npm pack --dry-run --cache .npm-cache",
+    "release:check": "npm run check && npm run pack:check",
+    "prepublishOnly": "npm run release:check"
+  },
+  "devDependencies": {
+    "eslint": "^10.9.1"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { PACKAGE_ROOT, readJson } from "./fs-utils.mjs";
+import { DEFAULT_INSTALL_DIR, init, status, update } from "./install.mjs";
+import { UPSTREAM, extractPort, loadArchive, materialize } from "./upstream.mjs";
+
+const HELP = `agentic-skills - install the ag-kit agent roles, skills, and workflows into any project
+
+Usage:
+  agentic-skills init    [options]   Download ag-kit and install the content into <path>/<dir>
+  agentic-skills update  [options]   Download ag-kit again and update installed files, preserving local edits
+  agentic-skills status  [options]   Show what is installed and which files were changed locally
+
+Options:
+  -p, --path <dir>        Project directory (default: current directory)
+  -d, --dir <name>        Install directory inside the project (default: ${DEFAULT_INSTALL_DIR})
+  -r, --ref <git-ref>     Upstream branch, tag, or commit to install (default: ${UPSTREAM.ref})
+      --archive <source>  Install from a local ag-kit .tar.gz or a URL instead of GitHub
+  -f, --force             Overwrite locally modified files
+      --dry-run           Download and show the plan without writing anything
+      --json              Print machine-readable output
+  -h, --help              Show this help
+  -v, --version           Show the package version
+
+Exit codes:
+  0  success
+  1  error
+  2  completed, but some files were skipped because they were modified locally
+`;
+
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  options: {
+    path: { type: "string", short: "p" },
+    dir: { type: "string", short: "d" },
+    ref: { type: "string", short: "r", default: UPSTREAM.ref },
+    archive: { type: "string" },
+    force: { type: "boolean", short: "f", default: false },
+    "dry-run": { type: "boolean", default: false },
+    json: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
+  },
+});
+
+const command = positionals[0];
+const log = (message) => {
+  if (!values.json) console.log(message);
+};
+
+const list = (label, items, format = (item) => item) => {
+  if (!items.length) return;
+  console.log(`\n${label} (${items.length}):`);
+  for (const item of items) console.log(`  ${format(item)}`);
+};
+
+/** Download the upstream archive and lay the ported tree out in a temp dir. */
+const fetchIncoming = async () => {
+  log(values.archive ? `Reading ${values.archive}` : `Downloading ${UPSTREAM.repository} at ${values.ref}`);
+  const buffer = await loadArchive({ ref: values.ref, archive: values.archive });
+  const port = extractPort(buffer);
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "agentic-skills-"));
+  try {
+    await materialize(port.files, dir);
+  } catch (error) {
+    await fs.rm(dir, { recursive: true, force: true });
+    throw error;
+  }
+  for (const warning of port.warnings) console.error(`warning: ${warning}`);
+  return {
+    dir,
+    upstream: {
+      repository: UPSTREAM.repository,
+      ref: values.archive ? null : values.ref,
+      commit: port.commit,
+      version: port.version,
+    },
+    cleanup: () => fs.rm(dir, { recursive: true, force: true }),
+  };
+};
+
+const describeUpstream = (upstream) => {
+  if (!upstream) return "unknown upstream";
+  const commit = upstream.commit ? ` (${upstream.commit.slice(0, 7)})` : "";
+  return `ag-kit ${upstream.version}${commit}`;
+};
+
+const printPlan = (result) => {
+  const { plan } = result;
+  const prefix = result.dryRun ? "[dry run] " : "";
+  console.log(`${prefix}${result.mode}: ${result.installDir}`);
+  console.log(`${prefix}source: ${describeUpstream(result.upstream)}`);
+  console.log(
+    `${prefix}added ${plan.add.length}, updated ${plan.update.length}, removed ${plan.remove.length}, ` +
+    `skipped ${plan.skip.length}, kept ${plan.keep.length}, unchanged ${plan.unchanged.length}`,
+  );
+  list("Skipped (modified locally; use --force to overwrite)", plan.skip, (item) => `${item.file}: ${item.reason}`);
+  list("Kept (removed upstream but modified locally)", plan.keep, (item) => `${item.file}: ${item.reason}`);
+  if (result.mode === "update" && result.hadManifest === false) {
+    console.log("\nNo manifest was found, so files that differ from upstream were skipped. Re-run with --force to overwrite them.");
+  }
+  if (result.mode === "init" && !result.dryRun) {
+    console.log(`\nPoint your assistant at ${path.join(result.installDir, "ARCHITECTURE.md")} to get the inventory.`);
+  }
+};
+
+const printStatus = (info) => {
+  console.log(`package:   ${info.package.packageName} ${info.package.packageVersion}`);
+  console.log(`target:    ${info.installDir}`);
+  if (!info.installed) {
+    console.log('status:    not installed (run "agentic-skills init")');
+    return;
+  }
+  if (!info.manifest) {
+    console.log("status:    installed without a manifest (not managed by agentic-skills)");
+  } else {
+    console.log(`installed: ${describeUpstream(info.manifest.upstream)} on ${info.manifest.updatedAt}`);
+  }
+  const counts = info.counts;
+  console.log(`files:     ${counts.tracked} tracked, ${counts.modified} modified, ${counts.missing} missing, ${counts.untracked} untracked`);
+  console.log('run "agentic-skills update --dry-run" to see what a fresh download would change');
+  list("Modified locally", info.modified);
+  list("Missing", info.missing);
+};
+
+try {
+  if (values.version) {
+    const pkg = await readJson(path.join(PACKAGE_ROOT, "package.json"));
+    console.log(pkg.version);
+  } else if (values.help || !command || command === "help") {
+    process.stdout.write(HELP);
+  } else if (command === "init" || command === "update") {
+    const incoming = await fetchIncoming();
+    try {
+      const options = {
+        path: values.path,
+        dir: values.dir,
+        force: values.force,
+        dryRun: values["dry-run"],
+        incomingDir: incoming.dir,
+        upstream: incoming.upstream,
+      };
+      const result = command === "init" ? await init(options) : await update(options);
+      if (values.json) console.log(JSON.stringify(result, null, 2));
+      else printPlan(result);
+      if (result.plan.skip.length || result.plan.keep.length) process.exitCode = 2;
+    } finally {
+      await incoming.cleanup();
+    }
+  } else if (command === "status") {
+    const info = await status({ path: values.path, dir: values.dir });
+    if (values.json) console.log(JSON.stringify(info, null, 2));
+    else printStatus(info);
+  } else {
+    console.error(`Unknown command: ${command}\n`);
+    process.stdout.write(HELP);
+    process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/src/fs-utils.mjs

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+
+export const PACKAGE_ROOT = path.resolve(currentDir, "..");
+
+const IGNORED_NAMES = new Set([".DS_Store", "Thumbs.db", "__pycache__"]);
+const IGNORED_SUFFIXES = [".pyc"];
+
+export const toPosix = (value) => value.split(path.sep).join("/");
+
+export const isIgnoredName = (name) =>
+  IGNORED_NAMES.has(name) || IGNORED_SUFFIXES.some((suffix) => name.endsWith(suffix));
+
+export const exists = async (target) => {
+  try {
+    await fs.access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const readJson = async (file) => JSON.parse(await fs.readFile(file, "utf8"));
+
+export const writeJson = async (file, data) => {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(data, null, 2)}\n`);
+};
+
+export const hashFile = async (file) =>
+  crypto.createHash("sha256").update(await fs.readFile(file)).digest("hex");
+
+/**
+ * Map of posix-relative file path to sha256 for every file under `root`.
+ * `ignorePrefixes` are posix-relative paths to skip entirely.
+ */
+export async function snapshotTree(root, { ignorePrefixes = [] } = {}) {
+  const snapshot = {};
+  if (!(await exists(root))) return snapshot;
+
+  const visit = async (dir) => {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (isIgnoredName(entry.name)) continue;
+      const absolute = path.join(dir, entry.name);
+      const relative = toPosix(path.relative(root, absolute));
+      if (ignorePrefixes.some((prefix) => relative === prefix || relative.startsWith(`${prefix}/`))) continue;
+      if (entry.isDirectory()) await visit(absolute);
+      else if (entry.isFile()) snapshot[relative] = await hashFile(absolute);
+    }
+  };
+
+  await visit(root);
+  return snapshot;
+}
+
+export async function copyFile(source, destination) {
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.copyFile(source, destination);
+}
+
+export async function removeEmptyParents(file, stopDir) {
+  const stop = path.resolve(stopDir);
+  let current = path.dirname(path.resolve(file));
+  while (current !== stop && current.startsWith(`${stop}${path.sep}`)) {
+    const entries = await fs.readdir(current).catch(() => null);
+    if (!entries || entries.length > 0) break;
+    await fs.rmdir(current);
+    current = path.dirname(current);
+  }
+}

package/src/install.mjs

@@ -0,0 +1,200 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import {
+  PACKAGE_ROOT,
+  copyFile,
+  exists,
+  readJson,
+  removeEmptyParents,
+  snapshotTree,
+  writeJson,
+} from "./fs-utils.mjs";
+
+export const DEFAULT_INSTALL_DIR = ".agents";
+export const METADATA_DIR = ".agentic-skills";
+export const MANIFEST_FILE = "manifest.json";
+export const MANIFEST_SCHEMA_VERSION = 1;
+
+export function resolveTarget({ path: projectPath, dir } = {}) {
+  const projectDir = path.resolve(projectPath || process.cwd());
+  const installDir = path.resolve(projectDir, dir || DEFAULT_INSTALL_DIR);
+  return {
+    projectDir,
+    installDir,
+    manifestPath: path.join(installDir, METADATA_DIR, MANIFEST_FILE),
+  };
+}
+
+export async function loadManifest(installDir) {
+  const manifestPath = path.join(installDir, METADATA_DIR, MANIFEST_FILE);
+  if (!(await exists(manifestPath))) return null;
+  try {
+    const manifest = await readJson(manifestPath);
+    if (manifest?.schemaVersion !== MANIFEST_SCHEMA_VERSION) return null;
+    if (!manifest.files || typeof manifest.files !== "object" || Array.isArray(manifest.files)) return null;
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+
+async function writeManifest(installDir, files, { previous = null, upstream = null } = {}) {
+  const now = new Date().toISOString();
+  const pkg = await readJson(path.join(PACKAGE_ROOT, "package.json"));
+  const manifest = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    packageName: pkg.name,
+    packageVersion: pkg.version,
+    upstream,
+    installedAt: previous?.installedAt || now,
+    updatedAt: now,
+    files,
+  };
+  await writeJson(path.join(installDir, METADATA_DIR, MANIFEST_FILE), manifest);
+  return manifest;
+}
+
+/**
+ * Three-way comparison between the installed tree, the incoming tree fetched
+ * from upstream, and the hashes recorded at the last install or update.
+ *
+ * - add:       incoming, not installed
+ * - update:    incoming, installed, unchanged locally since the last run (or --force)
+ * - skip:      incoming, installed, modified locally (left alone)
+ * - remove:    tracked before, gone from incoming, unchanged locally (or --force)
+ * - keep:      tracked before, gone from incoming, modified locally
+ * - unchanged: already identical to incoming
+ *
+ * Files the user created themselves are never tracked and never touched.
+ */
+export async function planUpdate({ installDir, incomingDir, manifest = null, force = false }) {
+  const current = await snapshotTree(installDir, { ignorePrefixes: [METADATA_DIR] });
+  const incoming = await snapshotTree(incomingDir);
+  const previous = manifest?.files || {};
+  const files = [...new Set([...Object.keys(current), ...Object.keys(incoming), ...Object.keys(previous)])].sort();
+
+  const plan = { add: [], update: [], skip: [], remove: [], keep: [], unchanged: [], incoming };
+
+  for (const file of files) {
+    const currentHash = current[file];
+    const incomingHash = incoming[file];
+    const previousHash = previous[file];
+
+    if (incomingHash !== undefined) {
+      if (currentHash === undefined) plan.add.push(file);
+      else if (currentHash === incomingHash) plan.unchanged.push(file);
+      else if (currentHash === previousHash || force) plan.update.push(file);
+      else {
+        plan.skip.push({
+          file,
+          reason: previousHash === undefined
+            ? "differs from upstream and is not tracked by a manifest"
+            : "modified locally",
+        });
+      }
+      continue;
+    }
+
+    if (currentHash === undefined || previousHash === undefined) continue;
+    if (currentHash === previousHash || force) plan.remove.push(file);
+    else plan.keep.push({ file, reason: "removed upstream but modified locally" });
+  }
+
+  return plan;
+}
+
+export async function applyPlan({ installDir, incomingDir, plan }) {
+  for (const file of [...plan.add, ...plan.update]) {
+    await copyFile(path.join(incomingDir, file), path.join(installDir, file));
+  }
+  for (const file of plan.remove) {
+    const target = path.join(installDir, file);
+    await fs.rm(target, { force: true });
+    await removeEmptyParents(target, installDir);
+  }
+}
+
+async function hasContent(dir) {
+  if (!(await exists(dir))) return false;
+  const entries = await fs.readdir(dir);
+  return entries.length > 0;
+}
+
+export async function init(options = {}) {
+  const { installDir } = resolveTarget(options);
+  const { incomingDir, upstream = null } = options;
+  const force = Boolean(options.force);
+
+  if (!force && (await hasContent(installDir))) {
+    throw new Error(
+      `${installDir} already exists and is not empty. Run "agentic-skills update" to update it, ` +
+      "or pass --force to overwrite managed files in place.",
+    );
+  }
+
+  const manifest = await loadManifest(installDir);
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force });
+  if (!options.dryRun) {
+    await applyPlan({ installDir, incomingDir, plan });
+    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
+  }
+  return { mode: "init", installDir, plan, upstream, dryRun: Boolean(options.dryRun) };
+}
+
+export async function update(options = {}) {
+  const { installDir } = resolveTarget(options);
+  const { incomingDir, upstream = null } = options;
+
+  if (!(await exists(installDir))) {
+    throw new Error(`${installDir} does not exist. Run "agentic-skills init" first.`);
+  }
+
+  const manifest = await loadManifest(installDir);
+  const plan = await planUpdate({ installDir, incomingDir, manifest, force: Boolean(options.force) });
+  if (!options.dryRun) {
+    await applyPlan({ installDir, incomingDir, plan });
+    await writeManifest(installDir, plan.incoming, { previous: manifest, upstream });
+  }
+  return {
+    mode: "update",
+    installDir,
+    plan,
+    upstream,
+    hadManifest: Boolean(manifest),
+    dryRun: Boolean(options.dryRun),
+  };
+}
+
+/** Local report only; nothing is fetched. */
+export async function status(options = {}) {
+  const { installDir } = resolveTarget(options);
+  const pkg = await readJson(path.join(PACKAGE_ROOT, "package.json"));
+  const packageMeta = { packageName: pkg.name, packageVersion: pkg.version };
+
+  if (!(await exists(installDir))) {
+    return { installed: false, installDir, package: packageMeta };
+  }
+
+  const manifest = await loadManifest(installDir);
+  const current = await snapshotTree(installDir, { ignorePrefixes: [METADATA_DIR] });
+  const tracked = manifest?.files || {};
+  const modified = Object.keys(tracked).filter((file) => current[file] !== undefined && current[file] !== tracked[file]);
+  const missing = Object.keys(tracked).filter((file) => current[file] === undefined);
+  const untracked = Object.keys(current).filter((file) => tracked[file] === undefined);
+
+  return {
+    installed: true,
+    installDir,
+    manifest,
+    package: packageMeta,
+    counts: {
+      tracked: Object.keys(tracked).length,
+      modified: modified.length,
+      missing: missing.length,
+      untracked: untracked.length,
+    },
+    modified,
+    missing,
+    untracked,
+  };
+}

package/src/tar.mjs

@@ -0,0 +1,91 @@
+/**
+ * Minimal reader for the tar archives GitHub serves from codeload.
+ *
+ * Handles ustar headers with the prefix field, pax extended headers for
+ * long paths, and the pax global header that git archive uses to record the
+ * commit id. Links, devices, and other entry types are skipped.
+ */
+
+const BLOCK = 512;
+
+const text = (buffer, offset, length) => {
+  const end = buffer.indexOf(0, offset);
+  const stop = end === -1 || end > offset + length ? offset + length : end;
+  return buffer.subarray(offset, stop).toString("utf8");
+};
+
+const octal = (buffer, offset, length) => {
+  const value = text(buffer, offset, length).trim();
+  return value ? parseInt(value, 8) : 0;
+};
+
+const isZeroBlock = (block) => block.every((byte) => byte === 0);
+
+/** Parse pax records of the form "<length> <key>=<value>\n". */
+export function parsePax(data) {
+  const records = {};
+  let offset = 0;
+  while (offset < data.length) {
+    const space = data.indexOf(0x20, offset);
+    if (space === -1) break;
+    const length = parseInt(data.subarray(offset, space).toString("utf8"), 10);
+    if (!Number.isFinite(length) || length <= 0) break;
+    const record = data.subarray(space + 1, offset + length).toString("utf8");
+    const equals = record.indexOf("=");
+    if (equals !== -1) records[record.slice(0, equals)] = record.slice(equals + 1).replace(/\n$/, "");
+    offset += length;
+  }
+  return records;
+}
+
+/**
+ * Yield { type, name, data } for every entry. `type` is "file", "directory",
+ * or "global" (a pax global header, with its records under `pax`).
+ */
+export function* readTar(buffer) {
+  let offset = 0;
+  let pendingPax = null;
+  let pendingLongName = null;
+
+  while (offset + BLOCK <= buffer.length) {
+    const header = buffer.subarray(offset, offset + BLOCK);
+    if (isZeroBlock(header)) break;
+
+    const size = octal(header, 124, 12);
+    const typeflag = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
+    const prefix = text(header, 345, 155);
+    let name = text(header, 0, 100);
+    if (prefix) name = `${prefix}/${name}`;
+
+    const dataStart = offset + BLOCK;
+    const dataEnd = dataStart + size;
+    if (dataEnd > buffer.length) throw new Error("Truncated tar archive");
+    const data = buffer.subarray(dataStart, dataEnd);
+    offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+
+    if (typeflag === "x") {
+      pendingPax = parsePax(data);
+      continue;
+    }
+    if (typeflag === "g") {
+      yield { type: "global", name, data, pax: parsePax(data) };
+      continue;
+    }
+    // GNU tar stores paths over 100 characters in an "L" entry that describes
+    // the entry after it. "K" does the same for a link target, and we skip
+    // links, so its payload is discarded.
+    if (typeflag === "L") {
+      pendingLongName = text(data, 0, data.length);
+      continue;
+    }
+    if (typeflag === "K") continue;
+
+    if (pendingLongName) name = pendingLongName;
+    if (pendingPax?.path) name = pendingPax.path;
+    pendingLongName = null;
+    pendingPax = null;
+
+    if (typeflag === "0" || typeflag === "7") yield { type: "file", name, data };
+    else if (typeflag === "5") yield { type: "directory", name, data };
+  }
+}

package/src/upstream.mjs

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import zlib from "node:zlib";
+import { isIgnoredName } from "./fs-utils.mjs";
+import { readTar } from "./tar.mjs";
+
+export const UPSTREAM = {
+  repository: "https://github.com/vudovn/ag-kit",
+  owner: "vudovn",
+  name: "ag-kit",
+  ref: "main",
+};
+
+/** Upstream path to installed path. Everything listed here is copied verbatim. */
+export const PORTED = {
+  directories: {
+    ".agents/agent": "agent",
+    ".agents/skills": "skills",
+    ".agents/workflows": "workflows",
+  },
+  files: {
+    ".agents/ARCHITECTURE.md": "ARCHITECTURE.md",
+    LICENSE: "LICENSE",
+  },
+  version: ".agents/VERSION",
+};
+
+/**
+ * Sections of the upstream ARCHITECTURE.md that describe the content. The
+ * others describe upstream's wiring into its own runtime and are dropped.
+ * Matching is by heading text after any leading emoji, so "## 🤖 Agents (20)"
+ * matches "Agents".
+ */
+export const ARCHITECTURE_SECTIONS = [
+  "Agents",
+  "Skills",
+  "Workflows",
+  "Skill Loading Protocol",
+  "Quick Reference",
+];
+
+/**
+ * The real upstream archive is under 1 MB compressed and a few MB expanded.
+ * The cap bounds decompression, which is where a small hostile file turns into
+ * gigabytes; the timeout bounds a server that accepts a connection and stalls.
+ */
+export const MAX_EXPANDED_BYTES = 128 * 1024 * 1024;
+export const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+const megabytes = (bytes) => `${Math.round(bytes / 1024 / 1024)} MB`;
+
+export const archiveUrl = (ref = UPSTREAM.ref) =>
+  `https://codeload.github.com/${UPSTREAM.owner}/${UPSTREAM.name}/tar.gz/${ref.split("/").map(encodeURIComponent).join("/")}`;
+
+const download = async (url, fetchImpl) => {
+  let response;
+  try {
+    response = await fetchImpl(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+  } catch (error) {
+    if (error?.name === "TimeoutError" || error?.name === "AbortError") {
+      throw new Error(`Timed out after ${DOWNLOAD_TIMEOUT_MS / 1000}s downloading ${url}`);
+    }
+    throw new Error(`Could not download ${url}: ${error?.message || error}`);
+  }
+  if (!response.ok) {
+    throw new Error(`Download failed with ${response.status} ${response.statusText} for ${url}`);
+  }
+  return Buffer.from(await response.arrayBuffer());
+};
+
+/**
+ * Get the upstream archive as a gzip buffer. `archive` may be a local .tar.gz
+ * path or an http(s) URL; otherwise the GitHub archive for `ref` is fetched.
+ */
+export async function loadArchive({ ref = UPSTREAM.ref, archive = null, fetchImpl = globalThis.fetch } = {}) {
+  if (archive) {
+    if (/^https?:\/\//.test(archive)) return download(archive, fetchImpl);
+    return fs.readFile(archive);
+  }
+  return download(archiveUrl(ref), fetchImpl);
+}
+
+/**
+ * Archive entries are attacker-controlled whenever --archive is used, so a
+ * path is accepted only when it cannot escape the directory it is written
+ * into: no absolute paths, no "." or ".." segments, no backslashes (a
+ * separator on Windows), and no NUL bytes.
+ */
+export function assertSafeRelativePath(relative, source = relative) {
+  const unsafe =
+    !relative ||
+    relative.includes("\0") ||
+    relative.includes("\\") ||
+    path.posix.isAbsolute(relative) ||
+    path.win32.isAbsolute(relative) ||
+    relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..");
+
+  if (unsafe) {
+    throw new Error(`The archive contains an unsafe path and was not extracted: ${JSON.stringify(source)}`);
+  }
+  return relative;
+}
+
+const headingTitle = (heading) =>
+  heading.replace(/^##\s*/, "").replace(/^[^\p{L}\p{N}]+/u, "").trim().toLowerCase();
+
+const matchesSection = (heading, name) => {
+  const title = headingTitle(heading);
+  const wanted = name.toLowerCase();
+  return title === wanted || title.startsWith(`${wanted} `) || title.startsWith(`${wanted}(`);
+};
+
+/**
+ * Keep only the ARCHITECTURE.md sections that describe the installed content.
+ * When upstream no longer has one of the expected sections the file is
+ * returned verbatim with a warning, so an upstream restructure never blocks
+ * an install.
+ */
+export function portArchitecture(markdown, { commit, version } = {}) {
+  const sections = [];
+  let current = null;
+  for (const line of markdown.split(/\r?\n/)) {
+    if (/^## /.test(line)) {
+      current = { heading: line, lines: [] };
+      sections.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+
+  const picked = [];
+  for (const name of ARCHITECTURE_SECTIONS) {
+    const section = sections.find((candidate) => matchesSection(candidate.heading, name));
+    if (!section) {
+      return {
+        text: markdown,
+        warning: `Upstream ARCHITECTURE.md has no "${name}" section, so it was installed verbatim.`,
+      };
+    }
+    picked.push(section);
+  }
+
+  const trim = (lines) => {
+    const body = [...lines];
+    while (body.length && (body.at(-1).trim() === "" || body.at(-1).trim() === "---")) body.pop();
+    while (body.length && body[0].trim() === "") body.shift();
+    return body;
+  };
+
+  const source = [version ? `\`${version}\`` : null, commit ? `commit \`${commit.slice(0, 7)}\`` : null]
+    .filter(Boolean)
+    .join(", ");
+  const header = [
+    "# ag-kit Architecture",
+    "",
+    `> Inventory of the agents, skills, and workflows installed from [ag-kit](${UPSTREAM.repository})${source ? ` (${source})` : ""}.`,
+    "> Sections about upstream tooling that is not part of this install were omitted; the sections below are upstream text, unchanged.",
+  ].join("\n");
+
+  const body = picked
+    .map((section) => [section.heading, "", ...trim(section.lines)].join("\n"))
+    .join("\n\n---\n\n");
+
+  return { text: `${header}\n\n---\n\n${body}\n`, warning: null };
+}
+
+/**
+ * Turn the upstream archive into the tree to install.
+ * Returns { files: Map<installedPath, Buffer>, commit, version, warnings }.
+ */
+export function extractPort(archive, { filterArchitecture = true } = {}) {
+  let tar;
+  try {
+    tar = zlib.gunzipSync(archive, { maxOutputLength: MAX_EXPANDED_BYTES });
+  } catch (error) {
+    if (error?.code === "ERR_BUFFER_TOO_LARGE") {
+      throw new Error(`The archive expands to more than ${megabytes(MAX_EXPANDED_BYTES)}, which is far bigger than ag-kit. Refusing to extract it.`);
+    }
+    throw new Error(`The archive could not be read as a .tar.gz: ${error?.message || error}`);
+  }
+
+  const raw = new Map();
+  let commit = null;
+
+  for (const entry of readTar(tar)) {
+    if (entry.type === "global") {
+      const comment = entry.pax?.comment;
+      if (comment && /^[0-9a-f]{40}$/.test(comment)) commit = comment;
+      continue;
+    }
+    if (entry.type !== "file") continue;
+    const slash = entry.name.indexOf("/");
+    if (slash === -1) continue;
+    raw.set(entry.name.slice(slash + 1), entry.data);
+  }
+
+  const layoutHint = "Upstream may have changed its layout. Try --ref with a known-good tag, or update agentic-skills.";
+  const files = new Map();
+
+  for (const [from, to] of Object.entries(PORTED.directories)) {
+    let count = 0;
+    for (const [name, data] of raw) {
+      if (!name.startsWith(`${from}/`)) continue;
+      const relative = name.slice(from.length + 1);
+      if (relative.split("/").some(isIgnoredName)) continue;
+      files.set(assertSafeRelativePath(`${to}/${relative}`, name), data);
+      count += 1;
+    }
+    if (count === 0) throw new Error(`The archive has no files under ${from}. ${layoutHint}`);
+  }
+
+  for (const [from, to] of Object.entries(PORTED.files)) {
+    if (!raw.has(from)) throw new Error(`The archive has no ${from}. ${layoutHint}`);
+    files.set(to, raw.get(from));
+  }
+
+  let version = "unknown";
+  if (raw.has(PORTED.version)) {
+    version = raw.get(PORTED.version).toString("utf8").trim() || version;
+  } else if (raw.has("package.json")) {
+    try {
+      version = JSON.parse(raw.get("package.json").toString("utf8")).version || version;
+    } catch {
+      /* keep "unknown" */
+    }
+  }
+
+  const warnings = [];
+  if (filterArchitecture) {
+    const ported = portArchitecture(files.get("ARCHITECTURE.md").toString("utf8"), { commit, version });
+    files.set("ARCHITECTURE.md", Buffer.from(ported.text, "utf8"));
+    if (ported.warning) warnings.push(ported.warning);
+  }
+
+  return { files, commit, version, warnings };
+}
+
+/** Write an extracted tree to a directory, never outside it. */
+export async function materialize(files, dir) {
+  const root = path.resolve(dir);
+  for (const [relative, data] of files) {
+    const target = path.resolve(root, ...relative.split("/"));
+    if (!target.startsWith(root + path.sep)) {
+      throw new Error(`Refusing to write ${JSON.stringify(relative)} outside ${root}`);
+    }
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, data);
+  }
+}