Use this skill to turn a plugin idea into a working FastGPT official plugin. Treat this file as self-contained onboarding text: first make sure the developer has the repository, tools, and dependencies, then scaffold and implement the plugin.
Start here whenever the current machine may not already have this repo ready.
-
Check whether you are inside this repository:
git rev-parse --show-toplevel
git remote -v
test -f package.json && node -p "require('./package.json').name"
The expected package name is @fastgpt/official-plugins. The expected upstream repository is labring/fastgpt-official-plugins.
-
Install or verify required tools:
git --version
gh --version
node --version
corepack --version
pnpm --version
Required versions from the root package.json:
- Node.js
>=22
- pnpm
>=10, preferably the pinned pnpm@10.28.2
If gh is missing, guide the developer to install GitHub CLI from the official instructions at https://github.com/cli/cli#installation.
Common installation choices:
brew install gh
winget install --id GitHub.cli
For Linux, follow the official distro-specific instructions in the GitHub CLI README. After installation, run:
gh auth login
gh auth status
-
Fork and clone the official repository with partial clone and sparse checkout.
Pick the target plugin path first. The default is:
PLUGIN_DIR=packages/tools/<plugin-name>
Then create the fork and clone only the top-level files plus the target tool directory:
gh repo fork labring/fastgpt-official-plugins --clone --default-branch-only -- --filter=blob:none --sparse
cd fastgpt-official-plugins
git remote get-url upstream || git remote add upstream https://github.com/labring/fastgpt-official-plugins.git
git remote set-url upstream https://github.com/labring/fastgpt-official-plugins.git
git fetch --filter=blob:none upstream
git sparse-checkout set --cone --sparse-index --skip-checks "$PLUGIN_DIR"
mkdir -p packages/tools
git remote -v
--filter=blob:none avoids downloading file contents until needed. sparse-checkout keeps the working tree focused on root config files and the requested plugin directory. --skip-checks allows a brand-new plugin directory that does not exist in the remote tree yet.
If the repo is already cloned, make sure remotes are useful and narrow the checkout to the current plugin:
PLUGIN_DIR=packages/tools/<plugin-name>
git remote -v
git remote get-url upstream || git remote add upstream https://github.com/labring/fastgpt-official-plugins.git
git remote set-url upstream https://github.com/labring/fastgpt-official-plugins.git
git fetch --filter=blob:none upstream
git sparse-checkout init --cone --sparse-index
git sparse-checkout set --cone --sparse-index --skip-checks "$PLUGIN_DIR"
mkdir -p packages/tools
To inspect nearby examples without pulling every tool, list tool names from the tree and add only the relevant reference directories:
git ls-tree -d --name-only HEAD:packages/tools
git sparse-checkout add --skip-checks packages/tools/<reference-plugin>
-
Install dependencies:
corepack enable
corepack prepare pnpm@10.28.2 --activate
pnpm install
If installation needs network or sandbox approval, request approval for the install/fetch command and continue after it succeeds.
-
Create a working branch:
git checkout -b codex/<plugin-name>
-
Collect just enough requirements:
- plugin name and target directory
- plugin type:
tool or tool-suite
- Chinese and English name/description
- inputs, outputs, secrets, and external APIs
- expected behavior, errors, and 1-3 test examples
-
If core requirements are missing, ask at most three focused questions. If defaults are obvious, proceed and state the assumptions.
-
Read the CLI skill before scaffolding when dependencies are installed:
sed -n '1,240p' node_modules/@fastgpt-plugin/cli/skills/cli-usage/SKILL.md
Prefer its documented commands and flags. If behavior is unclear, run:
pnpm fastgpt-plugin <command> --help
-
Create the initial skeleton with @fastgpt-plugin/cli.
Default for this repo:
pnpm fastgpt-plugin create <plugin-name> --type tool --cwd packages/tools --description "<description>"
For a tool suite:
pnpm fastgpt-plugin create <plugin-name> --type tool-suite --cwd packages/tools --description "<description>"
-
Resolve and read the SDK-shipped development skills from the generated plugin directory. These SDK skills are the source of truth for plugin implementation rules.
cd packages/tools/<plugin-name>
SDK_FACTORY_ROOT=$(
node --input-type=module -e '
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const pkg = "@fastgpt-plugin/sdk-factory";
let dir = path.dirname(fileURLToPath(await import.meta.resolve(pkg)));
while (dir !== path.dirname(dir)) {
const file = path.join(dir, "package.json");
if (fs.existsSync(file) && JSON.parse(fs.readFileSync(file, "utf8")).name === pkg) {
console.log(dir);
process.exit(0);
}
dir = path.dirname(dir);
}
throw new Error(`Cannot find package root for ${pkg}`);
'
)
sed -n '1,220p' "$SDK_FACTORY_ROOT/skills/fastgpt-plugin-development/SKILL.md"
sed -n
sed -n
-
