Use this skill to turn a non-technical beginner's plugin idea, step by step, into a runnable, testable FastGPT plugin that can be submitted as a PR.
Beginner communication rules
- Communicate in Chinese by default; keep commands, code identifiers, and file names in English.
- Give the user only one small step at a time, with copyable commands and success indicators.
- When requirements are missing, ask at most three focused questions; when the default is obvious, proceed directly and state the assumption.
- Explain terms the first time they appear:
toolis a callable capability,tool-suiteis a group of related capabilities. - Do not let the user paste secrets in the chat. Use
.env, a local secret file, or the CLI's--secrets-file, and confirm that these files will not enter Git. - Explain the impact before installing, pulling from the network, publishing, pushing, or creating a PR; request authorization only when the current environment requires it.
Overall process
- Prepare the environment.
- Understand the requirements and choose the plugin type.
- Create the skeleton and develop the plugin.
- Test and debug locally.
- Publish the source code/package and submit a PR.
1. Prepare the environment
First detect the state of the user's machine:
git --version
gh --version
node -v
corepack --version
pnpm -v
pnpm fastgpt-plugin --help
When tools are missing, give installation commands by operating system:
# macOS
brew install git gh node
corepack enable
corepack prepare pnpm@10.28.2 --activate
# Windows PowerShell
winget install --id Git.Git -e
winget install --id GitHub.cli -e
winget install --id OpenJS.NodeJS.LTS -e
corepack enable
corepack prepare pnpm@10.28.2 --activate
# Ubuntu/Debian
sudo apt update
sudo apt install -y git curl nodejs npm
npm install -g corepack
corepack enable
corepack prepare pnpm@10.28.2 --activate
Then configure GitHub and Git identity:
gh auth login
gh auth status
git config --global user.name "<your-name>"
git config --global user.email "<your-email>"
If a repository already exists:
git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set --no-cone '/*' '!/packages/tools/*'
pnpm install
The Node and pnpm versions follow the current repository's package.json file's engines and packageManager .
In fastgpt-community-plugins , do not run git submodule update --init --recursivewithout a path; when a certain plugin is needed, only initialize packages/tools/<pluginId>。
2. Determine the requirements and plugin type
First collect just enough information:
- What should the plugin do in one sentence?
- What inputs are needed? What final output does FastGPT need to get?
- Does it call an external API? Does this API require a key or token?
- Is this one action, or multiple related actions?
- Give 1-3 examples, preferably including a failure or edge case.
Choose the plugin type:
tool: a single independent action, such as checking the weather, text conversion, calling an API endpoint, or computing a result.tool-suite: multiple related actions sharing a domain, credentials, or client, such as Notion's search/create/update, or a CRM's customers/orders/tickets.
For beginners, recommend toolfirst; choose tool-suiteonly when the user explicitly needs multiple related capabilities. A single tool can later be extended into a toolset.
Before coding, determine the integration form:
- No external service: pure computation, formatting, parsing, or local conversion.
- Credential-free public API: focus on handling network errors, rate limiting, and empty results.
- API requiring credentials: define
secrets, explain how to obtain the key, and never hardcode it. - File-type plugins: clarify upload/download behavior and test with small files.
3. Development
Before creating the skeleton, read the CLI usage instructions first:
sed -n '1,240p' node_modules/@fastgpt-plugin/cli/skills/cli-usage/SKILL.md
If that file does not exist, read the CLI help:
pnpm fastgpt-plugin create --help
pnpm fastgpt-plugin build --help
pnpm fastgpt-plugin check --help
pnpm fastgpt-plugin pack --help
pnpm fastgpt-plugin debug --help
Create a single tool:
pnpm fastgpt-plugin create <plugin-name> --type tool --cwd <target-parent> --description "<description>"
Create a toolset:
pnpm fastgpt-plugin create <plugin-name> --type tool-suite --cwd <target-parent> --description "<description>"
Choose the target directory:
- In
fastgpt-official-plugins, placed by default underpackages/tools。 - In this community index repository, plugins should first be developed in a standalone source repository; when adding to the index, place them as a submodule pinned to a fixed commit under
packages/tools/<pluginId>。 - When the user only wants a local prototype, create it in a clearly named working directory, and explain that publishing still requires a GitHub repository.
After generating, read the files before editing:
find <plugin-dir> -maxdepth 2 -type f | sort
sed -n '1,220p' <plugin-dir>/package.json
sed -n '1,240p' <plugin-dir>/index.ts
Implement according to the template structure:
- Keep
package.jsonscripts and dependency style consistent with the template. - Community plugin repositories must be independently installable and buildable, use explicit versions for dependencies, and keep their own
packageManagerandpnpm-lock.yaml, and do not usecatalog:orworkspace:。 - The entry file is only responsible for the manifest, schemas, and handler wiring.
- When the template provides
src/, put reusable runtime logic undersrc/。 - Keep the input/output schema consistent with the user-visible configuration.
- Only add
secrets。 - Add a concise
README.md, including purpose, inputs, outputs, secrets, examples, and local test commands. - Before adding dependencies, first look for existing utility functions and patterns in adjacent plugins or templates.
4. Testing and debugging
First run the local scripts in the plugin directory:
pnpm test
pnpm build
Then run the CLI validation:
pnpm fastgpt-plugin build --entry <plugin-dir> --output <plugin-dir>/dist
pnpm fastgpt-plugin check --entry <plugin-dir> --output <plugin-dir>/dist
pnpm fastgpt-plugin pack --entry <plugin-dir> --dist <plugin-dir>/dist --output <plugin-dir>
Debug with sample input:
pnpm fastgpt-plugin debug <plugin-dir> --run --input '{"example":"value"}'
When secrets are needed, use a local ignored file:
printf '{ "apiKey": "replace-me" }\n' > .secrets.local.json
pnpm fastgpt-plugin debug <plugin-dir> --run --input-file test/input.json --secrets-file .secrets.local.json
When helping newcomers troubleshoot:
- First read the complete error message.
- Determine which category the failure belongs to: installation, TypeScript, schema/config, runtime API, or packaging.
- Fix only one cause at a time, and rerun the minimal failing command.
- Keep sample inputs small and stable.
- Generate
.pkgbefore moving on to publishing discussions.
5. Publishing and submitting a PR
In the plugin source repository:
git status
git checkout -b feat/<pluginId>
git add .
git commit -m "feat(<pluginId>): add FastGPT plugin"
git push -u origin feat/<pluginId>
gh pr create --title "feat(<pluginId>): add FastGPT plugin" --body "<summary>"
In this community index repository, after the source repository has been pushed:
git rev-parse HEAD
git submodule add <plugin-repo-url> packages/tools/<pluginId>
pnpm run plugin -- add --from packages/tools/<pluginId>
plugin The CLI will, according to schemas/registry.ts , update plugins.json, and can automatically infer the source URL and commit from the submodule via git/gh . Then run:
pnpm run validate
pnpm test
When preparing the community index PR, use the existing plugin-discovery skill to generate the intake bundle. The PR should include the registry entry and the submodule pointer; validation results and policy review findings are recorded via GitHub PR comments.
Before creating the PR, confirm:
git statuscontains only the files expected for this change.- No secrets, tokens, or
.env、.secrets.local.json。 README.mdallows newcomers to complete configuration and testing.- The PR body includes command output or a brief validation summary.
When delivering to the user, explain: which files were changed, the chosen plugin type, key assumptions, commands executed, validation results, the PR URL, and remaining risks such as unverified external APIs.