mirror of https://github.com/CopilotKit/CopilotKit.git synced 2026-09-14 16:26:20 +08:00

Files

T

History

Ben Taylor e2702705e9 refactor(skills): replace nine knowledge skills with two entry points (#7029 )

## What

Replaces nine packaged knowledge skills with two entry points.

| | |
| --- | --- |
| `copilotkit` | The `copilotkit-docs` MCP server: four search tools and
two explore tools, which corpus answers which question, and the
instruction not to answer from memory. |
| `copilotkit-cli` | The CLI, led by `copilotkit verify --json`. |

**Deleted:** `copilotkit-setup`, `copilotkit-develop`,
`copilotkit-integrations`, `copilotkit-debug`, `copilotkit-upgrade`,
`copilotkit-agui`, `copilotkit-contribute`, `copilotkit-self-update`,
and the three package-generated skills (`react-core`, `runtime`,
`a2ui-renderer`).

Net: **-28,851 / +335 lines.**

**Kept, and out of scope here:** `setup-slack-channel`,
`channels-setup`, `copilotkit-channels`, `inspector-docs`,
`inspector-workbench`, `intelligence-docs`. The first three are
procedures rather than knowledge; the last three are internal
maintenance, not part of the public product. Their disposition is a
separate call.

## Why

The packaged skills had become a second copy of the documentation, and a
copy goes stale silently.

- `runtime` and `react-core` were roughly 60% transcribed API surface.
Of the remaining "Common Mistakes" prose, most already existed on a docs
page.
- Four claims in the deleted skills contradicted the source they cited.
One of them reached a shipped PR (#7005) before it was caught, and had
to be corrected in `14231a6169` — the skill asserted that server tools
cannot render UI because the browser never sees a tool-call start event,
which `packages/runtime/src/agent/index.ts:1519,1584` contradicts.
- `copilotkit-debug` was 1,289 lines of hand-written triage. Since
#1180, `copilotkit verify` covers version skew, CORS, and transcription
directly, which is most of what those lines described.
- Nothing in telemetry or in the issue tracker suggests the
per-lifecycle split was load-bearing for anyone.

The gotchas worth keeping were moved onto docs pages first, in #6993,
#6997 and #7021's predecessors, so this PR removes rather than discards.

## Also in this PR

- `skills` dropped from the `files` field of `@copilotkit/react-core`,
`@copilotkit/runtime` and `@copilotkit/a2ui-renderer`, so the tarballs
stop carrying a copy.
- `RESERVED_LIFECYCLE_SLUGS` in `scripts/sync-plugin-skills.ts` goes
from 14 entries to 8.
- `.claude-plugin/plugin.json` and `marketplace.json` descriptions no
longer advertise the deleted lifecycle.
- `/build-with-agents` (56,393 distinct viewers in 90 days) named three
deleted skills in a table and told the reader to "Use the
copilotkit-setup skill to get started". Rewritten for the two-skill
model.
- `README.md` and the two stale cross-references in
`copilotkit-channels/SKILL.md` updated.
- One dead `skills/copilotkit-setup/SKILL.md` entry removed from
`ALIAS_ALLOWLIST` in `scripts/validate-intelligence-env-names.ts`.

`scripts/__tests__/public-skill-drift.test.ts` guarded specific wording
inside files that no longer exist. It is now a link guard instead: every
`docs.copilotkit.ai` path a packaged skill names has to resolve to a
page in this repo, and the two entry points have to stay free of a
transcribed API surface (asserted as: no `sources.md` other than the
channels skill's).

## Supersedes

Closed in favour of this one, with a comment on each: #7017 (the CLI
skill, whose content seeded `copilotkit-cli`), #7021, #7023.

## Needs a decision from someone else

- **#5689** (@onsclom) is a skill-lift eval for `copilotkit-setup`,
which this PR deletes. No file overlap, so it will not conflict, but the
eval target is gone. Austin's call whether to retarget it at
`copilotkit` or drop it.
- **#6636** (community, for #6125) fixes
`packages/react-core/skills/react-core/references/agent-access.md`, the
one file it touches, which this PR deletes. Needs a reply to the author
explaining why, not a silent close.
- **Install-command drift, unresolved.** `README.md` and
`showcase/.../cli/cli.mdx` say `npx copilotkit@latest skills install`;
`/build-with-agents` says `npx skills add CopilotKit/CopilotKit/skills
-y`. Both commands work. Picking one retires a shipped CLI command,
which belongs in the Intelligence repo, so this PR leaves both in place
and changes only the prose around them.

## Testing

The worktree has no `node_modules`, so `lefthook` could not resolve
`tsx`, `oxlint` or `nx` and the commit used `--no-verify`. Every gate
the hook would have run was run by hand against the repo's own binaries,
and the pre-commit failure output was the "command not found" line in
each case, not a gate verdict.

`pnpm check:plugin-skills` — the mirror gate, which also enforces orphan
deletion:

```
$ tsx scripts/sync-plugin-skills.ts --check
plugin skill mirror in sync
```

`pnpm check:intelligence-env-names`:

```
$ tsx scripts/validate-intelligence-env-names.ts
Intelligence env var names and hosts are canonical.
```

Both script suites:

```
$ vitest run scripts/__tests__/public-skill-drift.test.ts scripts/__tests__/sync-plugin-skills.test.ts
 Test Files  2 passed (2)
      Tests  16 passed (16)
```

**Mutation-checked the new link guard**, so it is not passing for the
wrong reason. Appending `See
[nope](https://docs.copilotkit.ai/this-page-does-not-exist).` to
`skills/copilotkit/SKILL.md`:

```
⎯⎯⎯⎯⎯⎯⎯ Failed Tests 1 ⎯⎯⎯⎯⎯⎯⎯
+   "skills/copilotkit/SKILL.md: /this-page-does-not-exist",
 Test Files  1 failed (1)
      Tests  1 failed | 3 passed (4)
```

Restored, back to 4 passed. The guard already caught one real mistake of
mine while I was writing the skill: I had linked `/custom-look-and-feel`
from the nav list without checking, and the page is
`/custom-look-and-feel/css`.

`oxfmt` on the four changed TypeScript files: no changes. Both plugin
manifests re-parsed as JSON after editing.

MDX: `build-with-agents.mdx` changes are prose, one table body and one
fence body. Its JSX tag inventory is byte-identical to `origin/main`:

```
$ diff <(git show origin/main:$f | grep -o '</\?[A-Z][A-Za-z]*' | sort | uniq -c) \
       <(grep -o '</\?[A-Z][A-Za-z]*' $f | sort | uniq -c) && echo IDENTICAL
IDENTICAL
```

`https://docs.copilotkit.ai/build-with-agents` returns 200, so the new
README link resolves.

Not run: the showcase docs build, which needs the per-entry
`node_modules` symlinks and the pretest generators this worktree does
not have. CI covers it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added `copilotkit` skill for searching current documentation and
source.
- Added `copilotkit-cli` skill for project verification, onboarding,
authentication, scaffolding, and CLI commands.
- Added guidance to use `copilotkit verify` to validate project wiring.

- **Documentation**
- Updated marketplace, plugin, README, and agent-building guidance for
the new skills.
  - Updated channel guidance to reference CLI-based setup.

- **Removals**
- Removed legacy setup, development, integration, debugging, upgrade,
contribution, and self-update skills.
  - Package distributions no longer include bundled skill documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-09-10 13:07:33 -05:00

public

chore: rename Enterprise Intelligence product copy

2026-08-24 09:38:15 -07:00

scripts

fix(docs): index reachable pages across docs build contexts

2026-09-05 03:05:49 +02:00

src

refactor(skills): replace nine knowledge skills with two entry points (#7029 )

2026-09-10 13:07:33 -05:00

.env.example

chore: rename Enterprise Intelligence product copy

2026-08-24 09:38:15 -07:00

.gitignore

…

Dockerfile

…

model-allowlist.json

docs: update Anthropic model references to Opus 4.8

2026-08-20 16:40:09 -07:00

next.config.ts

fix(docs): make the redirect suffix-aware and repair dead links the regeneration surfaced

2026-09-08 21:58:48 -05:00

package-lock.json

…

package.json

…

postcss.config.mjs

…

README.md

Revert "docs: define public AEO surface contract (#6458 )"

2026-08-13 10:45:31 -07:00

tsconfig.json

…

vercel.json

…

vitest.config.ts

…

README.md

Shell Docs

showcase/shell-docs is the Next.js app that builds and serves docs.copilotkit.ai. Author CopilotKit product documentation here, not in the retired top-level docs/ app.

Run Locally

Shell-docs is a standalone npm-based app. You do not need a root install just to run the docs app locally.

cd showcase/scripts
npm install

cd ../shell-docs
npm install
npm run dev

The local dev server runs on port 3003.

http://localhost:3003

The shell-docs npm lifecycle generates registry, demo-content, setup-content, and search data before dev, build, and typecheck.

Validate Changes

Run these from showcase/shell-docs:

npm run build
npm run typecheck
npm run test

For repo-level CI parity, prefer Nx when a shell-docs target is available in the current checkout and root dependencies are installed. For normal shell-docs local development, the npm commands above are the canonical path.

Authoring Recipes

Showcase-Driven Framework Docs

Showcase-driven frameworks use docs_mode: generated. The docs are assembled from showcase registry/generated data, demos, source regions, shared/root MDX, snippets, and sparse framework overrides.

To update showcase-driven docs:

Edit the showcase source of truth: manifests, demos, feature coverage, source regions, or registry inputs.
Edit shared/root MDX only when the change applies across generated frameworks.
Add sparse framework overrides only for real framework-specific differences.
Do not hand-edit generated files under src/data/frameworks/.
Validate routes, sidebar state, search results, snippets, and framework switching.

Authored Framework Docs

Authored frameworks use docs_mode: authored. The framework owns an MDX tree under src/content/docs/integrations/<docsFolder>/ with a meta.json sidebar.

To update authored docs:

Check getDocsFolder() in src/lib/registry.ts; the URL slug and folder name may differ.
Edit the MDX page under src/content/docs/integrations/<docsFolder>/.
Update that folder's meta.json when adding, removing, or moving pages.
Reuse shared snippets from src/content/snippets/ when content should stay consistent across frameworks.
Validate the framework route, sidebar, search result, and any shared snippet render.

Reference Docs

Edit API reference pages under src/content/reference/.

The v2 reference does not use meta.json; navigation is generated by walking the tree and reading each page's title and description frontmatter. Only the legacy reference/v1/ tree uses meta.json.

Snippets

Reusable snippets live under src/content/snippets/. Snippets may be rendered by root docs, authored framework pages, and showcase-driven framework pages, so keep them general unless the path is intentionally framework-specific.

Frontend Applicability

Frontend routes use page-level applicability metadata, independent from where the content is authored. A page can be authored MDX, showcase-generated content, mirrored protocol docs, or reference content and still be universal across frontends.

Use the frontend field in page frontmatter or meta.json when a root doc should appear in non-React frontend docs:

universal — render the same page under /<frontend>/....
frontend-variant — render only when a matching page exists under src/content/docs/frontends/<frontend>/....
hide — omit the page from frontend-scoped docs.

Do not use "showcase-driven" as a proxy for frontend availability. Showcase derivation is an authoring/source detail; frontend applicability controls routing and sidebar inclusion.

AG-UI Mirrored Docs

AG-UI protocol docs are authored upstream in ag-ui-protocol/ag-ui. The src/content/ag-ui/ tree is a downstream mirror rendered on the CopilotKit docs host. Change AG-UI docs upstream first, then sync the mirror back into shell-docs.

Top-Level Docs Symlink

The repository's top-level docs/ path is a symlink to showcase/shell-docs/ for contributor muscle memory. It is not a separate docs app. Do not recreate the old docs/content/docs/ tree; author CopilotKit docs in showcase/shell-docs/src/content/.