@lingxia/skill 0.8.0

package/README.md

@@ -0,0 +1,95 @@
+# @lingxia/skill
+
+The development skill for the [LingXia](https://github.com/LingXia-Dev/LingXia) cross-platform app framework, as a plain-markdown bundle you can install into any project.
+
+Open it with any AI coding tool that reads project files — Claude Code, the Claude Agent SDK, OpenAI Codex CLI, Cursor — and it will route the agent through LingXia's decision tree, recipes, CLI / component / native-API references as you build:
+
+- **standalone lxapps** — page-based mini-apps with a View + Logic split (React, Vue, or HTML view; JS Logic)
+- **native host apps** — Android, iOS, macOS, and Harmony shells embedding an lxapp
+- **Rust native extensions** — `#[lingxia::native]` routes and `lingxia::js` AppService extensions
+
+The on-disk layout follows the [Anthropic Skills convention](https://docs.claude.com/en/docs/claude-code/skills) — a `SKILL.md` entry with a frontmatter manifest plus relative sub-files. Tools that don't use that convention can still read the content directly; see _Codex CLI and other tools_ below.
+
+## Install
+
+The skill is opt-in — `lingxia new` doesn't bundle it, only prints a hint pointing at the install command below. Install it once per project (or globally per user):
+
+```bash
+# Project-scoped: ./.claude/skills/lingxia/
+npx @lingxia/skill install
+
+# User-scoped: ~/.claude/skills/lingxia/
+npx @lingxia/skill install --user
+
+# Custom location: <path>/lingxia/
+npx @lingxia/skill install --target ./agent
+
+# Preview without writing
+npx @lingxia/skill install --dry-run
+```
+
+Then open the project in your AI tool of choice. Claude tools discover `.claude/skills/` directly. Codex and many other agents should be given an `AGENTS.md` pointer; see the next section.
+
+### Codex CLI and other tools
+
+OpenAI Codex CLI reads repository instructions from `AGENTS.md`; it does not rely on Claude's `.claude/skills/` discovery path. Pass `--agents-md` and the installer writes the skill normally, then adds a small pointer block to `<project>/AGENTS.md` directing Codex at the installed `SKILL.md`:
+
+```bash
+npx @lingxia/skill install --agents-md
+```
+
+The block is fenced with HTML markers, so re-running the installer replaces it in place rather than appending duplicates. If the file doesn't exist yet, it's created; if it already has content, the pointer is appended.
+
+For Cursor, GitHub Copilot, or any agent that reads project markdown on demand, the default install plus a short rule in `.cursorrules` / `.github/copilot-instructions.md` pointing at `.claude/skills/lingxia/SKILL.md` works fine.
+
+### Other commands
+
+```bash
+npx @lingxia/skill where        # print the target install path
+npx @lingxia/skill uninstall    # remove the installed skill directory
+npx @lingxia/skill version      # print the skill version
+npx @lingxia/skill --help
+```
+
+(`uninstall` leaves `AGENTS.md` untouched — humans may have added content to it. Remove the LingXia block manually if you want it gone.)
+
+## Versioning
+
+`@lingxia/skill` ships with the same version number as the `lingxia` CLI and the rest of `@lingxia/*`. Pin a specific version when reproducibility matters:
+
+```bash
+npx @lingxia/skill@0.7.0 install
+```
+
+The skill's content documents the CLI surface; CLI releases that change a flag bump the skill version in lockstep.
+
+## What's inside
+
+```
+.claude/skills/lingxia/
+├── SKILL.md              # entry: decision tree, fast-path recipes, symptom router
+├── cli/reference.md      # every CLI command, flag, env var
+├── lxapp/
+│   ├── guide.md          # Page({}), useLxPage, events
+│   ├── components.md     # LxInput, LxVideo, LxPicker, LxMediaSwiper, LxNavigator
+│   ├── lx-api.md         # lx.* surface map + how to install @lingxia/types
+│   └── bridge.md         # setData, stream, channel mechanics
+├── app/
+│   ├── project.md        # lingxia.yaml + macOS App UI
+│   ├── apple-sdk.md      # iOS/macOS SDK embedding
+│   └── applinks.md       # universal links / app links
+├── native/development.md # Rust host: #[lingxia::native], HostAddon, facades
+├── reference/
+│   └── file-lifecycle.md # storage classes, downloadFile, FileManager
+└── skill-manifest.json   # package name + version + sync timestamp
+```
+
+## Where the content lives
+
+The canonical source is in the LingXia monorepo at [`docs/skill/`](https://github.com/LingXia-Dev/LingXia/tree/main/docs/skill). At publish time, `scripts/sync.mjs` copies that tree into `skill/` inside this package. End users of `@lingxia/skill` consume the synced copy.
+
+The skill itself doesn't depend on the LingXia repo at runtime — once installed, all cross-references are relative paths inside `skill/`.
+
+## License
+
+MIT

package/bin/install.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// `npx @lingxia/skill install [target]`
+//
+// Copies the LingXia agent skill into the chosen target. The skill is plain
+// markdown — readable by Claude Code, Claude Agent SDK, OpenAI Codex, Cursor,
+// or any tool that consumes project markdown — and ships in the layout that
+// Anthropic Skills expect (`<target>/lingxia/SKILL.md` + relative sub-files).
+//
+// Default targets:
+//   - <cwd>/.claude/skills/lingxia/     (project-scoped, default)
+//   - ~/.claude/skills/lingxia/         (--user)
+//   - <path>/lingxia/                   (--target <path>)
+//
+// For tools that look for a single AGENTS.md at the repo root (e.g. Codex CLI),
+// pass --agents-md to also write a tiny pointer file at <cwd>/AGENTS.md that
+// directs the agent at the installed SKILL.md.
+//
+// The skill source ships inside this package at `skill/`. It is synced from
+// `docs/skill/` in the LingXia monorepo at publish time. Reinstalling is
+// idempotent: existing target contents are removed first (unless --dry-run).
+
+import { cp, mkdir, readFile, rm, stat, readdir, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..");
+const source = join(pkgRoot, "skill");
+
+function parseArgs(argv) {
+  const args = {
+    _: [],
+    user: false,
+    force: false,
+    dryRun: false,
+    target: null,
+    agentsMd: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--user") args.user = true;
+    else if (a === "--force") args.force = true;
+    else if (a === "--dry-run" || a === "-n") args.dryRun = true;
+    else if (a === "--target") args.target = argv[++i];
+    else if (a === "--agents-md") args.agentsMd = true;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--version" || a === "-V") args.version = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: npx @lingxia/skill <command> [options]
+
+Install the LingXia agent skill into a project. The content is plain markdown
+and works with any AI coding tool that reads project files (Claude Code,
+Claude Agent SDK, OpenAI Codex, Cursor, ...).
+
+Commands:
+  install            Copy the skill into a target directory (default)
+  uninstall          Remove an installed copy
+  where              Print the path where install would write
+  version            Print the skill version
+
+Options:
+  --user             Install into ~/.claude/skills/lingxia/ instead of <cwd>/.claude/skills/lingxia/
+  --target <path>    Install into <path>/lingxia/ (overrides --user and cwd)
+  --agents-md        Also write <cwd>/AGENTS.md pointing at the installed skill
+                     (handy for Codex CLI and other tools that read AGENTS.md)
+  --force            Overwrite an existing install without prompting (default in non-interactive shells)
+  --dry-run, -n      Print actions without writing
+  -h, --help         Show help
+  -V, --version      Show version
+
+Examples:
+  npx @lingxia/skill install                                # Anthropic-style: .claude/skills/lingxia/
+  npx @lingxia/skill install --user                         # ~/.claude/skills/lingxia/
+  npx @lingxia/skill install --agents-md                    # also write AGENTS.md (Codex-friendly)
+  npx @lingxia/skill install --target docs/agent --dry-run  # custom target, preview only
+  npx @lingxia/skill uninstall
+`);
+}
+
+async function readVersion() {
+  const pkg = JSON.parse(
+    await readFile(join(pkgRoot, "package.json"), "utf8")
+  );
+  return pkg.version;
+}
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveTarget(args) {
+  if (args.target) {
+    const base = isAbsolute(args.target) ? args.target : resolve(process.cwd(), args.target);
+    return join(base, "lingxia");
+  }
+  if (args.user) {
+    return join(homedir(), ".claude", "skills", "lingxia");
+  }
+  return join(process.cwd(), ".claude", "skills", "lingxia");
+}
+
+async function ensureSourceExists() {
+  if (!(await exists(source))) {
+    console.error(
+      `error: skill source missing at ${source}\n` +
+        "       this package may not have been built/synced before publish."
+    );
+    process.exit(1);
+  }
+}
+
+async function install(args) {
+  await ensureSourceExists();
+  const target = resolveTarget(args);
+  const targetExists = await exists(target);
+  const agentsMdPath = args.agentsMd ? join(process.cwd(), "AGENTS.md") : null;
+
+  console.log(`source: ${source}`);
+  console.log(`target: ${target}`);
+  if (agentsMdPath) console.log(`agents-md: ${agentsMdPath}`);
+
+  if (args.dryRun) {
+    console.log("[dry-run] would " + (targetExists ? "replace" : "create") + " target");
+    if (agentsMdPath) {
+      console.log(
+        "[dry-run] would " +
+          ((await exists(agentsMdPath)) ? "append to" : "write") +
+          " AGENTS.md"
+      );
+    }
+    return;
+  }
+
+  if (targetExists) {
+    await rm(target, { recursive: true, force: true });
+  }
+  await mkdir(target, { recursive: true });
+  await cp(source, target, { recursive: true });
+
+  if (agentsMdPath) {
+    await writeAgentsMd(agentsMdPath, target);
+  }
+
+  console.log(`installed @lingxia/skill v${await readVersion()} → ${target}`);
+  console.log(
+    "The skill is plain markdown; open SKILL.md or point your AI coding tool at the install directory."
+  );
+}
+
+async function writeAgentsMd(agentsMdPath, skillTarget) {
+  const skillRelative = skillTarget.startsWith(process.cwd() + "/")
+    ? skillTarget.slice(process.cwd().length + 1)
+    : skillTarget;
+  const marker = "<!-- @lingxia/skill: AGENTS.md pointer -->";
+  const block = `${marker}
+## LingXia
+
+This project uses the LingXia cross-platform app framework. The development
+skill — decision tree, recipes, CLI / component / native API references —
+lives at:
+
+    ${skillRelative}/SKILL.md
+
+Start there. Sub-references are linked from that file using relative paths.
+${marker}
+`;
+
+  if (await exists(agentsMdPath)) {
+    const existing = await readFile(agentsMdPath, "utf8");
+    if (existing.includes(marker)) {
+      // Replace the previous block in-place.
+      const re = new RegExp(
+        `${marker}[\\s\\S]*?${marker}\\n?`,
+        "g"
+      );
+      await writeFile(agentsMdPath, existing.replace(re, block));
+    } else {
+      const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+      await writeFile(agentsMdPath, existing + sep + block);
+    }
+  } else {
+    await writeFile(agentsMdPath, `# AGENTS\n\n${block}`);
+  }
+}
+
+async function uninstall(args) {
+  const target = resolveTarget(args);
+  if (!(await exists(target))) {
+    console.log(`nothing to uninstall at ${target}`);
+    return;
+  }
+  if (args.dryRun) {
+    console.log(`[dry-run] would remove ${target}`);
+    return;
+  }
+  await rm(target, { recursive: true, force: true });
+  console.log(`removed ${target}`);
+}
+
+async function where(args) {
+  console.log(resolveTarget(args));
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv);
+
+  if (args.help) return printHelp();
+  if (args.version) {
+    console.log(await readVersion());
+    return;
+  }
+
+  const cmd = args._[0] ?? "install";
+
+  switch (cmd) {
+    case "install":
+      return install(args);
+    case "uninstall":
+      return uninstall(args);
+    case "where":
+      return where(args);
+    case "version":
+      console.log(await readVersion());
+      return;
+    default:
+      console.error(`unknown command: ${cmd}\n`);
+      printHelp();
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lingxia/skill",
+  "version": "0.8.0",
+  "private": false,
+  "description": "Agent skill for the LingXia cross-platform app framework. Installs a markdown skill bundle into your project so AI coding tools — Claude Code, Claude Agent SDK, OpenAI Codex, Cursor, or any agent that reads project markdown — can build lxapps, host apps, and native Rust extensions on LingXia.",
+  "type": "module",
+  "bin": {
+    "lingxia-skill": "bin/install.mjs"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "scripts/sync.mjs",
+    "README.md"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync.mjs",
+    "prepack": "node scripts/sync.mjs"
+  },
+  "keywords": [
+    "lingxia",
+    "lxapp",
+    "cross-platform",
+    "ai-tooling",
+    "agent-skill",
+    "skill",
+    "claude-code",
+    "claude-agent-sdk",
+    "codex",
+    "cursor"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LingXia-Dev/LingXia.git",
+    "directory": "packages/lingxia-skill"
+  },
+  "homepage": "https://github.com/LingXia-Dev/LingXia/tree/main/packages/lingxia-skill",
+  "bugs": {
+    "url": "https://github.com/LingXia-Dev/LingXia/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/sync.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// Sync the canonical skill source from docs/skill/ into packages/lingxia-skill/skill/.
+//
+// Run during `npm run sync` (manual) and `prepack` (automatic before publish).
+// The published tarball contains only the synced `skill/` copy — the canonical
+// `docs/skill/` source is not part of the published package.
+//
+// If the canonical source is not reachable (e.g. consumers running scripts
+// from the installed package), the sync is skipped silently — the `skill/`
+// directory already shipped in the tarball is authoritative.
+
+import { cp, mkdir, rm, stat, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(here, "..");
+const repoRoot = resolve(pkgRoot, "..", "..");
+const source = join(repoRoot, "docs", "skill");
+const target = join(pkgRoot, "skill");
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  if (!(await exists(source))) {
+    // Running outside the monorepo (e.g. inside an installed @lingxia/skill
+    // tarball). Nothing to sync; ship as-is.
+    console.log(
+      `[sync] skipped — source not found at ${source} (expected when running from an installed package)`
+    );
+    return;
+  }
+
+  if (await exists(target)) {
+    await rm(target, { recursive: true, force: true });
+  }
+  await mkdir(target, { recursive: true });
+  await cp(source, target, { recursive: true });
+
+  // Write a small manifest so consumers can introspect the skill version
+  // without reading SKILL.md.
+  const pkgJson = JSON.parse(
+    await readFile(join(pkgRoot, "package.json"), "utf8")
+  );
+  const manifest = {
+    name: pkgJson.name,
+    version: pkgJson.version,
+    entry: "SKILL.md",
+    syncedAt: new Date().toISOString(),
+  };
+  await writeFile(
+    join(target, "skill-manifest.json"),
+    JSON.stringify(manifest, null, 2) + "\n"
+  );
+
+  console.log(`[sync] copied ${source} → ${target}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});