Skip to content

docs(skill): delegate plugin rules to sdk-factory skills #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FinleyGe wants to merge 1 commit into
base: main
Choose a base branch
from
+75 −23
Open

docs(skill): delegate plugin rules to sdk-factory skills #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 75 additions & 23 deletions .agents/skills/develop-fastgpt-plugin/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,23 +54,47 @@ Start here whenever the current machine may not already have this repo ready.
gh auth status
```

3. Fork and clone the official repository with `gh`:
3. Fork and clone the official repository with partial clone and sparse checkout.

Pick the target plugin path first. The default is:

```bash
PLUGIN_DIR=packages/tools/<plugin-name>
```

Then create the fork and clone only the top-level files plus the target tool directory:

```bash
gh repo fork labring/fastgpt-official-plugins --clone
gh repo fork labring/fastgpt-official-plugins --clone --default-branch-only -- --filter=blob:none --sparse
cd fastgpt-official-plugins
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 upstream
git fetch --filter=blob:none upstream
git sparse-checkout set --cone --sparse-index --skip-checks "$PLUGIN_DIR"
mkdir -p packages/tools
git remote -v
```

If the repo is already cloned, make sure remotes are useful:
`--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:

```bash
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 upstream
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:

```bash
git ls-tree -d --name-only HEAD:packages/tools
git sparse-checkout add --skip-checks packages/tools/<reference-plugin>
```

4. Install dependencies:
Expand Down Expand Up @@ -126,26 +150,52 @@ Start here whenever the current machine may not already have this repo ready.
pnpm fastgpt-plugin create <plugin-name> --type tool-suite --cwd packages/tools --description "<description>"
```

5. Inspect generated files before editing. Match existing project patterns from nearby plugins, usually:
- `package.json`
- `index.ts`
- `config.ts`
- `src/index.ts`
- `test/`
- `README.md`
- `logo.svg`
5. 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.

```bash
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.

6. 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:

```bash
git sparse-checkout add --skip-checks packages/tools/fetchUrl packages/tools/searchApi
```

6. Implement the plugin:
- keep user-facing labels bilingual when the surrounding template does
- define `zod` input/output schemas in sync with `config.ts`
- put runtime behavior in `src/index.ts`
- keep `index.ts` focused on manifest, schemas, and handler wiring
- add secrets only for real credentials; never hardcode keys or tokens
- preserve existing package scripts and monorepo conventions
7. Implement the plugin according to the SDK-shipped skills, the generated template, and nearby project patterns. Preserve existing package scripts and monorepo conventions.

7. Add tests from the user's examples. Include success cases and the main validation/error case when practical.
8. Add tests from the user's examples. Include success cases and the main validation/error case when practical.

8. Verify from the plugin directory:
9. Verify from the plugin directory:

```bash
pnpm test
Expand All @@ -161,7 +211,9 @@ Start here whenever the current machine may not already have this repo ready.
- Default location is `packages/tools/<plugin-name>` unless the user specifies another path.
- Use `pnpm` in this repo; Node.js and pnpm must satisfy the root `package.json` engines.
- Keep `origin` pointing to the developer's fork and `upstream` pointing to `https://github.com/labring/fastgpt-official-plugins.git`.
- Use partial clone plus sparse checkout for new environments. Keep the sparse set to the target plugin directory and a small number of reference plugins; avoid checking out all `packages/tools/*` unless the task explicitly needs a repo-wide change.
- Prefer branch names like `codex/<plugin-name>` or `feat/<plugin-name>`.
- Treat `@fastgpt-plugin/sdk-factory` package skills as the implementation standard. This repository skill should not duplicate detailed SDK/plugin rules.
- Reuse utilities already present in nearby plugins before adding dependencies.
- Keep generated `dist/` and `.pkg` behavior consistent with existing plugins.
- If CLI creation fails because dependencies are missing or network access is needed, request approval for the install/fetch step and keep the partially generated files intact for diagnosis.
Expand Down