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 '1,320p' "$SDK_FACTORY_ROOT/skills/fastgpt-system-tool-development/SKILL.md"
sed -n '1,320p' "$SDK_FACTORY_ROOT/skills/fastgpt-sdk-factory/SKILL.md"
cd -
If the generated plugin cannot resolve @fastgpt-plugin/sdk-factory yet, run pnpm install from the repository root to link the new workspace package, then retry this step.
Use the SDK-shipped skills for defineTool(), defineToolSet(), createToolHandler(), Zod schemas, secrets, host invocation, streaming, required files, avatar naming, and build/check/pack expectations. If this repository skill conflicts with SDK-shipped skills, follow the SDK-shipped skills for implementation details and this skill for repository setup and workflow.
-
Inspect generated files before editing. Match existing project patterns from nearby plugins and the SDK-shipped skills.
In sparse checkouts, add only 1-3 nearby reference plugins when needed:
git sparse-checkout add --skip-checks packages/tools/fetchUrl packages/tools/searchApi
-
Implement the plugin according to the SDK-shipped skills, the generated template, and nearby project patterns. Preserve existing package scripts and monorepo conventions.
-
Add tests from the user's examples. Include success cases and the main validation/error case when practical.
-
Verify from the plugin directory:
pnpm test
pnpm build
npx @fastgpt-plugin/cli check --entry . --output ./dist
pnpm pack
If package scripts differ, read package.json and use the local scripts. For repo-wide confidence after a shared change, run root-level pnpm type-check or pnpm biome-check.
