@fastmoss/cli 0.1.4 → 0.1.5

package/README.md

@@ -7,13 +7,21 @@ FastMoss CLI lets terminals and AI agents discover and call FastMoss MCP tools f
 Use the CLI together with the FastMoss CLI Agent Skill:
 
 - `@fastmoss/cli` installs the `fastmoss` command and executes tool calls.
-- `npx skills add FastMoss/cli -y -g` installs the Agent Skill so your agent knows which FastMoss tools exist, when to use them, and how to call them.
+- `npx skills add FastMoss/cli` installs the Agent Skill so your agent knows which FastMoss tools exist, when to use them, and how to call them.
 
-For agent workflows, install both:
+Install CLI:
 
 ```bash
 npm install -g @fastmoss/cli
+```
+
+Install Skill separately:
+
+```bash
 npx skills add FastMoss/cli -y -g
+npx skills add FastMoss/cli --agent claude-code
+# If your skills CLI supports --client:
+npx skills add FastMoss/cli --client claude
 ```
 
 ## About FastMoss

package/README.zh-CN.md

@@ -7,13 +7,21 @@ FastMoss CLI 用于在终端或 AI Agent 中发现并调用 FastMoss MCP 工具
 CLI 需要配合 FastMoss CLI Agent Skill 一起使用：
 
 - `@fastmoss/cli` 安装 `fastmoss` 命令，用于真正执行工具调用。
-- `npx skills add FastMoss/cli -y -g` 安装 Agent Skill，让你的 Agent 知道有哪些 FastMoss 工具、什么时候使用、怎么调用。
+- `npx skills add FastMoss/cli` 安装 Agent Skill，让你的 Agent 知道有哪些 FastMoss 工具、什么时候使用、怎么调用。
 
-Agent 工作流建议两个都安装：
+安装 CLI：
 
 ```bash
 npm install -g @fastmoss/cli
+```
+
+单独安装 Skill：
+
+```bash
 npx skills add FastMoss/cli -y -g
+npx skills add FastMoss/cli --agent claude-code
+# 如果你的 skills CLI 支持 --client：
+npx skills add FastMoss/cli --client claude
 ```
 
 ## 关于 FastMoss

package/bin/install-skill.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const path = require("node:path");
+const {
+  INSTALL_SKILL_USAGE,
+  installSkill,
+  parseInstallSkillArgs,
+} = require("../lib/runtime");
+
+async function main() {
+  let options;
+  try {
+    options = parseInstallSkillArgs(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n\n${INSTALL_SKILL_USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.help) {
+    process.stdout.write(INSTALL_SKILL_USAGE);
+    return;
+  }
+
+  await installSkill({
+    packageRoot: path.join(__dirname, ".."),
+    agent: options.agent,
+  });
+}
+
+main().catch((error) => {
+  process.stderr.write(`fastmoss-install-skill error: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/runtime.js

@@ -8,6 +8,19 @@ const { spawn } = require("node:child_process");
 
 const DEFAULT_DOWNLOAD_BASE_URL =
   "https://github.com/FastMoss/cli/releases/download";
+const SKILL_NAME = "fastmoss-cli";
+const INSTALL_SKILL_USAGE = `Usage: fastmoss-install-skill [--agent codex|claude|agents|all]
+
+Options:
+  -a, --agent <agent>   Install for a specific agent client.
+                         Supported: codex, claude, agents, all.
+  -h, --help            Show this help message.
+
+Environment:
+  FASTMOSS_SKILL_AGENT          Default agent for this command.
+  FASTMOSS_SKILL_DIR            Override the target skills directory.
+  FASTMOSS_SKIP_SKILL_INSTALL   Skip skill installation.
+`;
 
 const PLATFORM_TARGETS = {
   "darwin:x64": {
@@ -140,6 +153,156 @@ function shouldSkipDownload(env = process.env) {
   return value !== "" && value !== "0" && value !== "false";
 }
 
+function isTruthyEnv(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+
+function shouldSkipSkillInstall(env = process.env) {
+  return isTruthyEnv(env.FASTMOSS_SKIP_SKILL_INSTALL);
+}
+
+function normalizeSkillAgent(agent = "") {
+  const normalized = String(agent || "").trim().toLowerCase();
+  if (normalized === "" || normalized === "auto") {
+    return "auto";
+  }
+  if (normalized === "claude-code") {
+    return "claude";
+  }
+  if (normalized === "agent") {
+    return "agents";
+  }
+  return normalized;
+}
+
+function knownSkillTargets({ env = process.env, homeDir = os.homedir() } = {}) {
+  return {
+    codex: path.join(env.CODEX_HOME || path.join(homeDir, ".codex"), "skills"),
+    claude: path.join(
+      env.CLAUDE_HOME || path.join(homeDir, ".claude"),
+      "skills",
+    ),
+    agents: path.join(
+      env.AGENTS_HOME || path.join(homeDir, ".agents"),
+      "skills",
+    ),
+  };
+}
+
+function resolveSkillInstallTargets({
+  agent = "auto",
+  env = process.env,
+  homeDir = os.homedir(),
+} = {}) {
+  const override = String(env.FASTMOSS_SKILL_DIR || "").trim();
+  if (override !== "") {
+    return [override];
+  }
+
+  const targets = knownSkillTargets({ env, homeDir });
+  const normalizedAgent = normalizeSkillAgent(agent || env.FASTMOSS_SKILL_AGENT);
+
+  if (normalizedAgent === "all") {
+    return [targets.codex, targets.claude, targets.agents];
+  }
+  if (normalizedAgent === "auto") {
+    return Object.values(targets);
+  }
+  if (targets[normalizedAgent]) {
+    return [targets[normalizedAgent]];
+  }
+
+  throw new Error(
+    `Unsupported FastMoss skill agent: ${agent}. Supported agents: codex, claude, agents, all`,
+  );
+}
+
+function parseInstallSkillArgs(args = []) {
+  const result = {
+    agent: "",
+    help: false,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      continue;
+    }
+    if (arg === "--agent" || arg === "-a") {
+      const value = args[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`${arg} requires an agent value`);
+      }
+      result.agent = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${arg}`);
+  }
+
+  return result;
+}
+
+async function installSkill({
+  packageRoot = path.join(__dirname, ".."),
+  agent = "",
+  env = process.env,
+  homeDir = os.homedir(),
+  stderr = process.stderr,
+} = {}) {
+  if (shouldSkipSkillInstall(env)) {
+    stderr.write(
+      "Skipping FastMoss CLI skill installation because FASTMOSS_SKIP_SKILL_INSTALL is set.\n",
+    );
+    return { installed: [], skipped: true };
+  }
+
+  const sourceSkillDir = path.join(packageRoot, "skills", SKILL_NAME);
+  if (!(await directoryExists(sourceSkillDir))) {
+    throw new Error(`FastMoss CLI skill not found: ${sourceSkillDir}`);
+  }
+
+  let targetRoots = resolveSkillInstallTargets({
+    agent: agent || env.FASTMOSS_SKILL_AGENT || "auto",
+    env,
+    homeDir,
+  });
+
+  const isAuto =
+    String(env.FASTMOSS_SKILL_DIR || "").trim() === "" &&
+    normalizeSkillAgent(agent || env.FASTMOSS_SKILL_AGENT) === "auto";
+  if (isAuto) {
+    const existingRoots = [];
+    for (const targetRoot of targetRoots) {
+      if (await directoryExists(targetRoot)) {
+        existingRoots.push(targetRoot);
+      }
+    }
+    targetRoots = existingRoots;
+  }
+
+  if (targetRoots.length === 0) {
+    stderr.write(
+      "Skipping FastMoss CLI skill installation because no supported agent skill directory was found. Set FASTMOSS_SKILL_AGENT=codex or FASTMOSS_SKILL_DIR to install explicitly.\n",
+    );
+    return { installed: [], skipped: true };
+  }
+
+  const installed = [];
+  for (const targetRoot of targetRoots) {
+    const targetSkillDir = path.join(targetRoot, SKILL_NAME);
+    await fs.promises.mkdir(targetRoot, { recursive: true });
+    await fs.promises.rm(targetSkillDir, { recursive: true, force: true });
+    await fs.promises.cp(sourceSkillDir, targetSkillDir, { recursive: true });
+    installed.push(targetSkillDir);
+    stderr.write(`Installed FastMoss CLI skill to ${targetSkillDir}\n`);
+  }
+
+  return { installed, skipped: false };
+}
+
 async function installCLI({
   version,
   env = process.env,
@@ -181,6 +344,18 @@ async function fileExists(filePath) {
   }
 }
 
+async function directoryExists(directoryPath) {
+  try {
+    const stat = await fs.promises.stat(directoryPath);
+    return stat.isDirectory();
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
 async function downloadFile(url, destination) {
   try {
     await downloadWithRedirects(url, destination, 0);
@@ -304,12 +479,16 @@ async function runCLI({
 
 module.exports = {
   DEFAULT_DOWNLOAD_BASE_URL,
+  INSTALL_SKILL_USAGE,
   buildDownloadURL,
   ensureBinary,
+  installSkill,
   installCLI,
+  parseInstallSkillArgs,
   resolveBinaryPath,
   resolveCacheRoot,
   resolveDownloadBaseURL,
+  resolveSkillInstallTargets,
   resolvePlatformTarget,
   runCLI,
 };

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@fastmoss/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "FastMoss CLI launcher for npm and npx",
   "license": "UNLICENSED",
   "private": false,
   "bin": {
-    "fastmoss": "bin/fastmoss.js"
+    "fastmoss": "bin/fastmoss.js",
+    "fastmoss-install-skill": "bin/install-skill.js"
   },
   "files": [
     "bin",
     "lib",
+    "skills",
     "README.md",
     "README.zh-CN.md"
   ],

package/skills/fastmoss-cli/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: fastmoss-cli
+description: Use when working with FastMoss CLI, FastMoss MCP tools, TikTok Shop product, creator, shop, video, ad, category, or market data, or when the user asks an agent to call FastMoss tools from the command line.
+---
+
+# FastMoss CLI
+
+Use the `fastmoss` command to discover and call FastMoss tools.
+
+## Startup checks
+
+1. Check the CLI is available:
+
+   ```bash
+   fastmoss --version
+   ```
+
+   If the FastMoss CLI is not installed or the command is not found, install it first:
+
+   ```bash
+   npm install -g @fastmoss/cli
+   ```
+
+   To update an existing FastMoss CLI installation to the latest package version, run:
+
+   ```bash
+   npm install -g @fastmoss/cli@latest
+   ```
+
+   Then continue to the login check.
+
+2. Check login status:
+
+   ```bash
+   fastmoss whoami
+   ```
+
+3. If not logged in, ask the user to provide or configure an API key:
+
+   ```bash
+   fastmoss login --api-key <your-api-key>
+   ```
+
+## Tool workflow
+
+1. Read `references/tool-call.md` before invoking a tool.
+2. Read `references/tools.md` to choose the tool and understand its parameters.
+3. Every `fastmoss call` MUST include agent client metadata. Prefer environment variables when making one or more calls in the same shell session:
+
+   ```bash
+   FASTMOSS_CLIENT_NAME="<client-name>" FASTMOSS_CLIENT_VERSION="<client-version>" fastmoss call --tool <tool_name> --args '<json>' --output mcp
+   ```
+
+   Or pass explicit flags for a single call:
+
+   ```bash
+   fastmoss call --client-name "<client-name>" --client-version "<client-version>" --tool <tool_name> --args '<json>' --output mcp
+   ```
+
+   Use the actual client name and version when available. Do not invent a version number; if the runtime does not expose a version, use the client name and omit the version only if the CLI allows it.
+
+Prefer `--output mcp` when an LLM or agent will read and reason over the tool response. Use `--output data` when the user needs a concise end-user payload. Use `--output rpc` only when debugging raw RPC responses.
+
+If the analysis result needs FastMoss detail-page links, call `fastmoss_detail_url_examples` first to get the link assembly rules, then build links from the returned examples and IDs in the analysis result.
+
+## References
+
+- `references/cli.md`: CLI command reference.
+- `references/tool-call.md`: safe calling patterns, quoting, output modes, and error handling.
+- `references/tools.md`: static FastMoss tool catalog index. Read the matching category file from this index instead of loading all tools at once.

package/skills/fastmoss-cli/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: FastMoss CLI
+short_description: Use FastMoss command-line tools from an agent.
+default_prompt: Use FastMoss CLI to find the right FastMoss tool, call it with JSON arguments, and summarize the result for the user.