[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69A92XM7GHX71ZFDQH1WRXD":3,"skill-same:01M69A92XM7GHX71ZFDQH1WRXD":78},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":6,"ownerHtmlUrl":54,"ownerBlogUrl":55,"ownerDescription":56,"updatedAt":57,"install":58,"resources":71},"01M69A92XM7GHX71ZFDQH1WRXD","pilotswarm-cli-builder",null,"Use when creating or updating a plugin-driven CLI\u002FTUI app on top of PilotSwarm. Covers plugin.json branding, agent\u002Fskill layout, worker modules, keybinding\u002Fhelp sync, and the DevOps sample structure.","microsoft\u002FPilotSwarm","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69A6RNK492A5JSNBTXANKX5",16,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-cli-builder\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"pilotswarm cli builder","cli builder","cli","builder","modules","when","top","branding","app","layout","worker","sample","structure","devops","use","tui","json","help","plugin","sync","2026-11-10 10:12:30",false,"---\nname: pilotswarm-cli-builder\ndescription: \"Use when creating or updating a plugin-driven CLI\u002FTUI app on top of PilotSwarm. Covers plugin.json branding, agent\u002Fskill layout, worker modules, keybinding\u002Fhelp sync, and the DevOps sample structure.\"\n---\n\n# PilotSwarm CLI Builder\n\nBuild layered CLI\u002FTUI apps on top of the shipped PilotSwarm interface.\n\n## Canonical References\n\n- Source quickstart: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fquickstart\u002Flocal.md`\n- CLI guide: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-apps.md`\n- CLI agent guide: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-agents.md`\n- Keybindings: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-guide\u002Fkeybindings.md`\n- DevOps sample: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Ftree\u002Fmain\u002Fexamples\u002Fdevops-command-center`\n\n## Preferred Structure\n\n```text\nmy-app\u002F\n├── .gitignore\n├── .env.example\n├── .model_providers.example.json\n├── package.json\n├── plugin\u002F\n│   ├── plugin.json\n│   ├── agents\u002F                 # optional named workflows\n│   ├── skills\u002F\n│   ├── .mcp.json\n│   └── session-policy.json\n├── scripts\u002F\n│   ├── run.sh\n│   └── cleanup-local-db.js\n├── worker-module.js\n└── README.md\n```\n\n## Workflow\n\n1. Identify whether the app should use the shipped TUI rather than a custom UI.\n2. Run a guided intake before scaffolding.\n3. Create `plugin\u002Fplugin.json` when the user wants app branding.\n4. Put reusable methods in `plugin\u002Fskills`, executable actions in worker tools or MCP servers, and use `plugin\u002Fagents\u002F*.agent.md` only for complex authored workflows or durable named entry points. Packages without agents remain valid and are progressively discoverable by Base Agent V2 sessions.\n5. Every generated `.agent.md` must include `schemaVersion: 1` and a `version` string. Use `version: 1.0.0` for new agents by default. When editing an existing agent, bump its `version` according to the app's versioning style; prefer SemVer when the app uses it.\n6. Treat `plugin\u002Fagents\u002Fdefault.agent.md` as the app-wide default overlay under PilotSwarm's embedded framework base. It is **not** a selectable session agent — PilotSwarm excludes it from the agent picker, the client rejects `createSession` calls with `agentId: \"default\"`, and the worker never adds it to `allowedAgentNames`. Do not name any other agent file `default`.\n6. Put reusable domain knowledge in `plugin\u002Fskills\u002F*\u002FSKILL.md`.\n7. Put runtime tool handlers in `worker-module.js`.\n8. Add `session-policy.json` if the user does not want generic sessions. The policy is enforced in both local and remote modes — the TUI reads it from the plugin directory even when there are no embedded workers. If the app should expose SDK-bundled optional agents, add them under `creation.bundledAgents`, for example `\"bundledAgents\": [\"generic-crawler\"]`; remote-mode picker metadata expands those names into creatable agents.\n9. Build `.env.example` and a gitignored `.env` by copying\u002Fadapting the PilotSwarm repo's example env shape when the user wants runnable scaffolding.\n10. Build `.model_providers.example.json` and a gitignored `.model_providers.json` by copying\u002Fadapting the PilotSwarm repo's example model-catalog shape when the scaffold needs a custom model catalog.\n11. Add checked-in scripts for launch and database cleanup (both local and remote modes).\n12. Make generated scripts executable and verify the executable bit.\n13. Add a README with local run instructions.\n14. When agents need durable structured memory or shared coordination state, use PilotSwarm's built-in facts tools (`store_fact`, `read_facts`, `delete_fact`) as the primary memory layer. They are available to every agent session by default, including system agents, so do not build a separate fact table unless the app truly requires it.\n15. When agents need recurring autonomous work, use durable timers: `cron(seconds=N, reason=\"...\")` for fixed intervals, `cron_at(minute=M, hour=H, tz=\"Area\u002FCity\", reason=\"...\")` for wall-clock schedules, and `cron(action=\"cancel\")` \u002F `cron_at(action=\"cancel\")` to stop. Do not build wall-clock jobs by waking every N minutes to check the clock.\n16. When generated agents delegate work, teach them to set `contract.wakeOn`: `any` for chatty work, `material_change` for finite task results and watcher changes, and `completion` only for actual terminal lifecycle outcomes. A finite child's ordinary final reply leaves it alive and idle, so generated parents validate the result and close it explicitly with `complete_agent`. Parent coordination is reactive: qualifying updates wake the parent automatically, so never generate a parent `wait`\u002F`cron` loop whose only action is `check_agents`.\n16. Agents can read their context usage (current tokens, token limit) from the session status. The TUI displays this in the status bar. Use this for agents that need to manage context window budgets or trigger compaction.\n17. If the app relies on downloadable files, document the shipped files inspector behavior: binary artifacts download intact, browser previews are download-only for non-text files, and the shared files browser supports download\u002Fdelete\u002Fopen flows.\n\n## Guided Intake Questions\n\nBefore generating files, ask:\n\n1. Should the app allow generic sessions under the default agent, or should usage be steered into named agents through a restrictive session policy?\n2. Should local startup use a bootstrap `GITHUB_TOKEN`, or will the first\n  runtime provider be created through Admin Console\u002Fmanagement API?\n3. What should be used for `DATABASE_URL` in `.env`?\n4. What local database name should the scaffold use? If unspecified, default it explicitly to the workspace name.\n5. If the user has not specified the agent roster, what workflows should the app support so you can derive the first agent set?\n6. Which topology should the scaffold target?\n   - local-only, using Docker Postgres\n   - standard remote topology using AKS + PostgreSQL + Blob storage\n   - custom topology supplied by the user\n\nDo not guess these answers when the user has not provided them. Offer the standard topology choices explicitly so the guided experience stays fast.\n\n## Env File Guidance\n\n- Treat `DATABASE_URL` as the canonical PostgreSQL connection input for LOCAL\n  mode (embedded workers). Remote attach needs only the portal URL:\n  `pilotswarm remote --api-url \u003Curl>` (auto Entra sign-in;\n  `--device-code` for headless hosts).\n- If the app needs a custom model catalog, check in a type-only\n  `.model_providers.example.json` and create the real `.model_providers.json`\n  locally from it. Add provider instances\u002Fcredentials through Admin or\n  `PilotSwarmManagementClient`, and configure `setModelDefault` \u002F\n  `setSystemModelDefault`; do not put credentials or `defaultModel` in new\n  catalogs.\n- Do not copy a sample `toolCatalog` opt-in without validating the target\n  Chat Completions endpoint. Omit it by default; router names do not enable\n  overflow dispatch. Put an approved policy on the model entry in its\n  provider-type catalog, not in a prompt or environment flag.\n- For local-first scaffolds, offer GitHub Copilot as the first runtime provider\n  type unless the user asks for another; do not hard-code a provider instance\n  or credential into the catalog.\n- For local-first scaffolds, do not include `LLM_PROVIDER_TYPE`, `LLM_ENDPOINT`, `LLM_API_KEY`, or `LLM_API_VERSION` by default.\n- Do not generate redundant `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, or `PGDATABASE` entries unless the user explicitly needs them.\n- Prefer a checked-in `.env.example` plus a local gitignored `.env`.\n- Prefer a checked-in `.model_providers.example.json` plus a local gitignored `.model_providers.json`.\n- Add both `.env` and `.model_providers.json` to `.gitignore` in runnable scaffolds.\n- Align the variable set with the chosen topology rather than blindly copying every sample env field.\n- For local-first scaffolds, the default env surface should usually be\n  `DATABASE_URL`; add `GITHUB_TOKEN` only when using bootstrap compatibility.\n- Add optional storage or deployment variables only when the topology requires them.\n- Only copy secrets from another repo or local file after the user explicitly asks for that behavior.\n\n## Database Cleanup Guidance\n\n- Generate a single cleanup script (`scripts\u002Fcleanup-local-db.js`) that handles both local and remote modes:\n  - `node scripts\u002Fcleanup-local-db.js` — uses `.env` (local)\n  - `node scripts\u002Fcleanup-local-db.js remote` — uses `.env.remote`\n- Parse `sslmode` from the `DATABASE_URL` and pass `ssl: { rejectUnauthorized: false }` to the `pg` client when connecting to Azure PostgreSQL. Follow the pattern in the DevOps sample's cleanup script.\n- Query session IDs from CMS (`copilot_sessions.sessions`) before dropping schemas.\n- In local mode, also remove local files for each session:\n  - Artifact directories at `~\u002F.copilot\u002Fartifacts\u002F\u003CsessionId>\u002F`\n  - Session state dirs at `~\u002F.copilot\u002Fsession-state\u002F\u003CsessionId>\u002F`\n  - Session store archives at `~\u002F.copilot\u002Fsession-store\u002F\u003CsessionId>.tar.gz` and `.meta.json`\n- In remote mode, skip local file cleanup (artifacts live in blob storage).\n- Drop `duroxide` and `copilot_sessions` schemas.\n- In remote mode, print the `kubectl rollout restart` command to recreate schemas.\n- Wire `package.json` scripts:\n  - `\"cleanup\": \"node scripts\u002Fcleanup-local-db.js\"`\n  - `\"cleanup:remote\": \"node scripts\u002Fcleanup-local-db.js remote\"`\n- Follow the pattern in PilotSwarm's DevOps sample `scripts\u002Fcleanup-local-db.js`.\n\n## Launcher Script Guidance\n\n- Generate a single `scripts\u002Frun.sh` that supports both local and remote modes:\n  - `.\u002Fscripts\u002Frun.sh` or `.\u002Fscripts\u002Frun.sh local` — local mode with embedded workers\n  - `.\u002Fscripts\u002Frun.sh remote` — remote mode connecting to AKS workers\n- Wire `package.json` scripts to point at `run.sh`:\n  - `\"start\": \".\u002Fscripts\u002Frun.sh\"` for local\n  - `\"start:remote\": \".\u002Fscripts\u002Frun.sh remote\"` for remote\n- Use `.env` for local mode and `.env.remote` for remote mode. The script selects the right file based on the mode argument.\n- Include preflight checks (env file exists, plugin dir exists, worker module exists for local).\n- Use `exec pilotswarm ...` for local and `exec pilotswarm remote ...` for remote.\n- Make the script executable and verify the executable bit after creation.\n- Keep compatibility workarounds in the launcher or `postinstall` scripts, not scattered across README steps.\n- A programmatic launcher can use `import { startTuiApp } from \"pilotswarm\"`\n  with `startTuiApp({ ...config, logFile: applicationLogPath })` to give each\n  application process its own diagnostic file. Custom paths create parent\n  directories and truncate on startup; invalid paths or tracing setup failures\n  reject, with no shared-log fallback. Omission keeps the legacy default.\n  This is an API option, not a CLI flag; see the CLI guide's\n  [Programmatic TUI Hosts](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-apps.md#programmatic-tui-hosts)\n  section for configuration and process-lifecycle details.\n\n## Validation Guidance\n\n- When the user wants runnable scaffolding, do more than write files: install dependencies and run a smoke test.\n- Do not treat `--help` output as proof that the app actually starts; prefer the real startup path when practical.\n- Check the declared runtime requirements and compare them against the current machine.\n- If scripts are intended to be run directly, verify direct execution rather than only `node script.js`.\n- If the scaffold defaults or inferred decisions matter, record them in the generated README.\n\n## Compatibility Guidance\n\n- If the generated app hits a known dependency issue during setup, isolate the workaround in setup or launcher scripts and explain why it exists.\n- Prefer deterministic fixes that can be re-applied after reinstall, such as `postinstall` or a verified pre-launch patch step, over one-off manual instructions.\n- Remove or simplify compatibility shims once the upstream dependency is fixed.\n\n## Agent Derivation Guidance\n\n- If the user names agents, scaffold those agents directly.\n- If the user only describes workflows, derive a starter agent set from those workflows and explain the mapping.\n- Keep the first scaffold minimal but coherent; do not invent a large agent roster without justification.\n\n## `plugin.json` Guidance\n\nUse `plugin.json` for metadata and TUI branding.\n\nExample:\n\n```json\n{\n  \"name\": \"devops\",\n  \"description\": \"DevOps Command Center\",\n  \"version\": \"1.0.0\",\n  \"tui\": {\n    \"title\": \"DevOps Command Center\",\n    \"splashFile\": \".\u002Ftui-splash.txt\"\n  }\n}\n```\n\n## Guardrails\n\n- Do not put tool implementations into agent markdown files.\n- Do not model developer-facing builder behavior as runtime system agents.\n- Keep prompts, skills, tool handlers, and branding in separate layers.\n- If you add or change TUI keybindings, update help\u002Fkeybinding surfaces together.\n- Treat system-agent `initialPrompt` as bootstrap startup content, not a user-authored chat line.\n- Assume apps consume `pilotswarm` and `pilotswarm-sdk`; built-in PilotSwarm plugins are embedded in those packages, not copied into the app repo.\n- Assume PostgreSQL-backed apps can opt into the built-in facts tools with agent `tools` lists instead of re-implementing fact storage from scratch.\n- Install the matching `pilotswarm`, `pilotswarm-sdk` and optional provider\n  tarballs from public GitHub Releases using\n  `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fquickstart\u002Fpackages.md`.\n  Preserve lock integrity and restore ignored downloads before `npm ci`.\n  Use installed binaries instead of registry-auto-fetching `npx -p` commands.\n- If the scaffold teaches artifact workflows, do not describe them as markdown-only; explain the shared binary-download contract too.\n","# PilotSwarm CLI Builder\n\nBuild layered CLI\u002FTUI apps on top of the shipped PilotSwarm interface.\n\n## Canonical References\n\n- Source quickstart: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fquickstart\u002Flocal.md`\n- CLI guide: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-apps.md`\n- CLI agent guide: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-agents.md`\n- Keybindings: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fuser-guide\u002Fkeybindings.md`\n- DevOps sample: `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Ftree\u002Fmain\u002Fexamples\u002Fdevops-command-center`\n\n## Preferred Structure\n\n```text\nmy-app\u002F\n├── .gitignore\n├── .env.example\n├── .model_providers.example.json\n├── package.json\n├── plugin\u002F\n│   ├── plugin.json\n│   ├── agents\u002F                 # optional named workflows\n│   ├── skills\u002F\n│   ├── .mcp.json\n│   └── session-policy.json\n├── scripts\u002F\n│   ├── run.sh\n│   └── cleanup-local-db.js\n├── worker-module.js\n└── README.md\n```\n\n## Workflow\n\n1. Identify whether the app should use the shipped TUI rather than a custom UI.\n2. Run a guided intake before scaffolding.\n3. Create `plugin\u002Fplugin.json` when the user wants app branding.\n4. Put reusable methods in `plugin\u002Fskills`, executable actions in worker tools or MCP servers, and use `plugin\u002Fagents\u002F*.agent.md` only for complex authored workflows or durable named entry points. Packages without agents remain valid and are progressively discoverable by Base Agent V2 sessions.\n5. Every generated `.agent.md` must include `schemaVersion: 1` and a `version` string. Use `version: 1.0.0` for new agents by default. When editing an existing agent, bump its `version` according to the app's versioning style; prefer SemVer when the app uses it.\n6. Treat `plugin\u002Fagents\u002Fdefault.agent.md` as the app-wide default overlay under PilotSwarm's embedded framework base. It is **not** a selectable session agent — PilotSwarm excludes it from the agent picker, the client rejects `createSession` calls with `agentId: \"default\"`, and the worker never adds it to `allowedAgentNames`. Do not name any other agent file `default`.\n6. Put reusable domain knowledge in `plugin\u002Fskills\u002F*\u002FSKILL.md`.\n7. Put runtime tool handlers in `worker-module.js`.\n8. Add `session-policy.json` if the user does not want generic sessions. The policy is enforced in both local and remote modes — the TUI reads it from the plugin directory even when there are no embedded workers. If the app should expose SDK-bundled optional agents, add them under `creation.bundledAgents`, for example `\"bundledAgents\": [\"generic-crawler\"]`; remote-mode picker metadata expands those names into creatable agents.\n9. Build `.env.example` and a gitignored `.env` by copying\u002Fadapting the PilotSwarm repo's example env shape when the user wants runnable scaffolding.\n10. Build `.model_providers.example.json` and a gitignored `.model_providers.json` by copying\u002Fadapting the PilotSwarm repo's example model-catalog shape when the scaffold needs a custom model catalog.\n11. Add checked-in scripts for launch and database cleanup (both local and remote modes).\n12. Make generated scripts executable and verify the executable bit.\n13. Add a README with local run instructions.\n14. When agents need durable structured memory or shared coordination state, use PilotSwarm's built-in facts tools (`store_fact`, `read_facts`, `delete_fact`) as the primary memory layer. They are available to every agent session by default, including system agents, so do not build a separate fact table unless the app truly requires it.\n15. When agents need recurring autonomous work, use durable timers: `cron(seconds=N, reason=\"...\")` for fixed intervals, `cron_at(minute=M, hour=H, tz=\"Area\u002FCity\", reason=\"...\")` for wall-clock schedules, and `cron(action=\"cancel\")` \u002F `cron_at(action=\"cancel\")` to stop. Do not build wall-clock jobs by waking every N minutes to check the clock.\n16. When generated agents delegate work, teach them to set `contract.wakeOn`: `any` for chatty work, `material_change` for finite task results and watcher changes, and `completion` only for actual terminal lifecycle outcomes. A finite child's ordinary final reply leaves it alive and idle, so generated parents validate the result and close it explicitly with `complete_agent`. Parent coordination is reactive: qualifying updates wake the parent automatically, so never generate a parent `wait`\u002F`cron` loop whose only action is `check_agents`.\n16. Agents can read their context usage (current tokens, token limit) from the session status. The TUI displays this in the status bar. Use this for agents that need to manage context window budgets or trigger compaction.\n17. If the app relies on downloadable files, document the shipped files inspector behavior: binary artifacts download intact, browser previews are download-only for non-text files, and the shared files browser supports download\u002Fdelete\u002Fopen flows.\n\n## Guided Intake Questions\n\nBefore generating files, ask:\n\n1. Should the app allow generic sessions under the default agent, or should usage be steered into named agents through a restrictive session policy?\n2. Should local startup use a bootstrap `GITHUB_TOKEN`, or will the first\n  runtime provider be created through Admin Console\u002Fmanagement API?\n3. What should be used for `DATABASE_URL` in `.env`?\n4. What local database name should the scaffold use? If unspecified, default it explicitly to the workspace name.\n5. If the user has not specified the agent roster, what workflows should the app support so you can derive the first agent set?\n6. Which topology should the scaffold target?\n   - local-only, using Docker Postgres\n   - standard remote topology using AKS + PostgreSQL + Blob storage\n   - custom topology supplied by the user\n\nDo not guess these answers when the user has not provided them. Offer the standard topology choices explicitly so the guided experience stays fast.\n\n## Env File Guidance\n\n- Treat `DATABASE_URL` as the canonical PostgreSQL connection input for LOCAL\n  mode (embedded workers). Remote attach needs only the portal URL:\n  `pilotswarm remote --api-url \u003Curl>` (auto Entra sign-in;\n  `--device-code` for headless hosts).\n- If the app needs a custom model catalog, check in a type-only\n  `.model_providers.example.json` and create the real `.model_providers.json`\n  locally from it. Add provider instances\u002Fcredentials through Admin or\n  `PilotSwarmManagementClient`, and configure `setModelDefault` \u002F\n  `setSystemModelDefault`; do not put credentials or `defaultModel` in new\n  catalogs.\n- Do not copy a sample `toolCatalog` opt-in without validating the target\n  Chat Completions endpoint. Omit it by default; router names do not enable\n  overflow dispatch. Put an approved policy on the model entry in its\n  provider-type catalog, not in a prompt or environment flag.\n- For local-first scaffolds, offer GitHub Copilot as the first runtime provider\n  type unless the user asks for another; do not hard-code a provider instance\n  or credential into the catalog.\n- For local-first scaffolds, do not include `LLM_PROVIDER_TYPE`, `LLM_ENDPOINT`, `LLM_API_KEY`, or `LLM_API_VERSION` by default.\n- Do not generate redundant `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, or `PGDATABASE` entries unless the user explicitly needs them.\n- Prefer a checked-in `.env.example` plus a local gitignored `.env`.\n- Prefer a checked-in `.model_providers.example.json` plus a local gitignored `.model_providers.json`.\n- Add both `.env` and `.model_providers.json` to `.gitignore` in runnable scaffolds.\n- Align the variable set with the chosen topology rather than blindly copying every sample env field.\n- For local-first scaffolds, the default env surface should usually be\n  `DATABASE_URL`; add `GITHUB_TOKEN` only when using bootstrap compatibility.\n- Add optional storage or deployment variables only when the topology requires them.\n- Only copy secrets from another repo or local file after the user explicitly asks for that behavior.\n\n## Database Cleanup Guidance\n\n- Generate a single cleanup script (`scripts\u002Fcleanup-local-db.js`) that handles both local and remote modes:\n  - `node scripts\u002Fcleanup-local-db.js` — uses `.env` (local)\n  - `node scripts\u002Fcleanup-local-db.js remote` — uses `.env.remote`\n- Parse `sslmode` from the `DATABASE_URL` and pass `ssl: { rejectUnauthorized: false }` to the `pg` client when connecting to Azure PostgreSQL. Follow the pattern in the DevOps sample's cleanup script.\n- Query session IDs from CMS (`copilot_sessions.sessions`) before dropping schemas.\n- In local mode, also remove local files for each session:\n  - Artifact directories at `~\u002F.copilot\u002Fartifacts\u002F\u003CsessionId>\u002F`\n  - Session state dirs at `~\u002F.copilot\u002Fsession-state\u002F\u003CsessionId>\u002F`\n  - Session store archives at `~\u002F.copilot\u002Fsession-store\u002F\u003CsessionId>.tar.gz` and `.meta.json`\n- In remote mode, skip local file cleanup (artifacts live in blob storage).\n- Drop `duroxide` and `copilot_sessions` schemas.\n- In remote mode, print the `kubectl rollout restart` command to recreate schemas.\n- Wire `package.json` scripts:\n  - `\"cleanup\": \"node scripts\u002Fcleanup-local-db.js\"`\n  - `\"cleanup:remote\": \"node scripts\u002Fcleanup-local-db.js remote\"`\n- Follow the pattern in PilotSwarm's DevOps sample `scripts\u002Fcleanup-local-db.js`.\n\n## Launcher Script Guidance\n\n- Generate a single `scripts\u002Frun.sh` that supports both local and remote modes:\n  - `.\u002Fscripts\u002Frun.sh` or `.\u002Fscripts\u002Frun.sh local` — local mode with embedded workers\n  - `.\u002Fscripts\u002Frun.sh remote` — remote mode connecting to AKS workers\n- Wire `package.json` scripts to point at `run.sh`:\n  - `\"start\": \".\u002Fscripts\u002Frun.sh\"` for local\n  - `\"start:remote\": \".\u002Fscripts\u002Frun.sh remote\"` for remote\n- Use `.env` for local mode and `.env.remote` for remote mode. The script selects the right file based on the mode argument.\n- Include preflight checks (env file exists, plugin dir exists, worker module exists for local).\n- Use `exec pilotswarm ...` for local and `exec pilotswarm remote ...` for remote.\n- Make the script executable and verify the executable bit after creation.\n- Keep compatibility workarounds in the launcher or `postinstall` scripts, not scattered across README steps.\n- A programmatic launcher can use `import { startTuiApp } from \"pilotswarm\"`\n  with `startTuiApp({ ...config, logFile: applicationLogPath })` to give each\n  application process its own diagnostic file. Custom paths create parent\n  directories and truncate on startup; invalid paths or tracing setup failures\n  reject, with no shared-log fallback. Omission keeps the legacy default.\n  This is an API option, not a CLI flag; see the CLI guide's\n  [Programmatic TUI Hosts](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fdeveloper\u002Fbuilding\u002Fcli-apps.md#programmatic-tui-hosts)\n  section for configuration and process-lifecycle details.\n\n## Validation Guidance\n\n- When the user wants runnable scaffolding, do more than write files: install dependencies and run a smoke test.\n- Do not treat `--help` output as proof that the app actually starts; prefer the real startup path when practical.\n- Check the declared runtime requirements and compare them against the current machine.\n- If scripts are intended to be run directly, verify direct execution rather than only `node script.js`.\n- If the scaffold defaults or inferred decisions matter, record them in the generated README.\n\n## Compatibility Guidance\n\n- If the generated app hits a known dependency issue during setup, isolate the workaround in setup or launcher scripts and explain why it exists.\n- Prefer deterministic fixes that can be re-applied after reinstall, such as `postinstall` or a verified pre-launch patch step, over one-off manual instructions.\n- Remove or simplify compatibility shims once the upstream dependency is fixed.\n\n## Agent Derivation Guidance\n\n- If the user names agents, scaffold those agents directly.\n- If the user only describes workflows, derive a starter agent set from those workflows and explain the mapping.\n- Keep the first scaffold minimal but coherent; do not invent a large agent roster without justification.\n\n## `plugin.json` Guidance\n\nUse `plugin.json` for metadata and TUI branding.\n\nExample:\n\n```json\n{\n  \"name\": \"devops\",\n  \"description\": \"DevOps Command Center\",\n  \"version\": \"1.0.0\",\n  \"tui\": {\n    \"title\": \"DevOps Command Center\",\n    \"splashFile\": \".\u002Ftui-splash.txt\"\n  }\n}\n```\n\n## Guardrails\n\n- Do not put tool implementations into agent markdown files.\n- Do not model developer-facing builder behavior as runtime system agents.\n- Keep prompts, skills, tool handlers, and branding in separate layers.\n- If you add or change TUI keybindings, update help\u002Fkeybinding surfaces together.\n- Treat system-agent `initialPrompt` as bootstrap startup content, not a user-authored chat line.\n- Assume apps consume `pilotswarm` and `pilotswarm-sdk`; built-in PilotSwarm plugins are embedded in those packages, not copied into the app repo.\n- Assume PostgreSQL-backed apps can opt into the built-in facts tools with agent `tools` lists instead of re-implementing fact storage from scratch.\n- Install the matching `pilotswarm`, `pilotswarm-sdk` and optional provider\n  tarballs from public GitHub Releases using\n  `https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Fdocs\u002Fquickstart\u002Fpackages.md`.\n  Preserve lock integrity and restore ignored downloads before `npm ci`.\n  Use installed binaries instead of registry-auto-fetching `npx -p` commands.\n- If the scaffold teaches artifact workflows, do not describe them as markdown-only; explain the shared binary-download contract too.\n",{"name":5,"description":7},"main","cecafe1ca7a9f2778a6166abdd12f6165d99f777","templates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-cli-builder",10,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-15 00:36:04",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add microsoft\u002FPilotSwarm --skill pilotswarm-cli-builder",{"tool":64,"command":65},"bunx","bunx skills add microsoft\u002FPilotSwarm --skill pilotswarm-cli-builder",{"tool":67,"command":68},"pnpm","pnpm dlx skills add microsoft\u002FPilotSwarm --skill pilotswarm-cli-builder","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-cli-builder\u002FSKILL.md",true,[72],{"path":73,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":76,"sourceHtmlUrl":77},"scripts\u002Fextract.py","SCRIPT","脚本",7638,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fagent-host-logs\u002Fscripts\u002Fextract.py",[79,100,115,128,152,175],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":44},"01M69A9CY8CXHED3AFC8DAT9G0","pilotswarm-three-tier","Reference for adding a Tier 3 worker AKS cluster to a PilotSwarm deployment. Covers provisioning, identity, Dockerfile changes, entrypoint, manifests, and verification.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-three-tier\u002FSKILL.md",[],[86,87,88,89,90,91,92,93,94,95,96,97,98,34,99],"pilotswarm three tier","three","entrypoint","manifests","for","changes","aks","verification","deployment","reference","dockerfile","identity","provisioning","cluster",{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":44},"01M69A9B6R5H88HJFEYC0P4R57","pilotswarm-sdk-builder","Use when creating or updating an SDK-first app on top of PilotSwarm. Covers the client\u002Fworker split, plugin layering, tool registration, tests, and the DevOps sample structure.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-sdk-builder\u002FSKILL.md",[],[107,108,27,109,110,42,38,111,29,30,112,32,113,34,35,36,114,37],"sdk","pilotswarm sdk builder","tool","first","client","split","tests","registration",{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":44},"01M69A99A43M97VTYZBCN1JQ1H","pilotswarm-portal-builder","Use when creating or updating a browser portal on top of PilotSwarm. Covers portal branding, plugin.json.portal, named-agent exposure, auth add-ons, and remote deployment wiring.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-portal-builder\u002FSKILL.md",[],[122,27,123,29,124,30,31,125,38,40,126,94,42,127],"pilotswarm portal builder","remote","wiring","add","browser","auth",{"skillNo":129,"name":130,"nameZh":6,"description":131,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":132,"categories":133,"keywords":137,"publishedAt":44},"01M69A97JZY10V1VE12NF4JR5A","pilotswarm-knowledge-harvester","Use when an SDK or CLI app needs to ingest external sources into durable, searchable knowledge and an open knowledge graph. Covers enabling the EnhancedFactStore + GraphStore providers, authoring a crawler:true agent, the crawl→graph→reader flow, ACL\u002FscopeKey evidence, and tests.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-knowledge-harvester\u002FSKILL.md",[134],{"categoryNo":135,"categoryName":136,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000021","资料检索与研究",[138,139,38,29,140,141,142,143,32,144,113,145,146,147,148,149,150,151,107,26],"knowledge","pilotswarm knowledge harvester","cli app","true","crawler","sources","authoring","crawl","ingest","evidence","reader","open","flow","knowledge graph",{"skillNo":153,"name":154,"nameZh":6,"description":155,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":156,"categories":157,"keywords":161,"publishedAt":44},"01M69A95Y3EWHSZ1TDFMXWAKX3","pilotswarm-hybrid-datastore","Use when a PilotSwarm app needs stock PostgreSQL for runtime storage plus HorizonDB for enhanced facts, semantic\u002Flexical search, and the knowledge graph. Covers env topology, horizonConfigFromEnv wiring, harvester agents, Azure secret\u002Fresource guidance, and the rule that Docker defaults remain stock Postgres.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-hybrid-datastore\u002FSKILL.md",[158],{"categoryNo":159,"categoryName":160,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000011","运维与部署",[162,163,164,32,165,166,167,168,38,138,151,169,170,171,172,173,29,124,90,174],"hybrid","pilotswarm hybrid datastore","storage","runtime","stock","postgres","guidance","search","postgresql","azure","env","docker","facts",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":181,"publishedAt":44},"01M69A94F4WR5CXDZ73N658DV0","pilotswarm-duroxide-versioning","Use when changing PilotSwarm durable orchestration behavior, continue-as-new state, or replay-sensitive control flow.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FPilotSwarm\u002Fblob\u002Fmain\u002Ftemplates\u002Fbuilder-agents\u002Fskills\u002Fpilotswarm-duroxide-versioning\u002FSKILL.md",[],[182,183,184,185,29,186,187,188,38,189,190,150,191],"pilotswarm duroxide versioning","versioning","orchestration","new","as","control","replay","behavior","continue","state"]