Contributing to AgentsKit.js

June 3, 2026 · View on GitHub

Thanks for being here. This guide gets you from git clone to merged PR with the least friction we know how to provide.

Read first: MANIFESTO.md. Every change is measured against the ten principles in there. If you're proposing something that conflicts with a principle, that's an RFC, not a PR.

Where to ask what

Kind of thing	Best place
Bug — reproducible	Bug Report issue
Feature you want	Feature Request issue
Docs problem	Documentation issue
Non-trivial design proposal	RFC issue, then a PR in `/rfcs/`
General question / "how do I"	GitHub Discussions
Security disclosure	`SECURITY.md` — private channel

Setup in 5 minutes

Prerequisites

Node.js 22+ (LTS recommended; Node 25 known-broken on the legacy Docusaurus app — use apps/docs-next instead)
pnpm 10+ (npm install -g pnpm if missing)
git with a global identity configured

Clone and install

git clone https://github.com/AgentsKit-io/agentskit.git
cd agentskit
pnpm install

That's it. The whole monorepo is now linked.

Verify everything works

pnpm build       # build all packages — under 10s with cache
pnpm test        # run all tests — under 30s
pnpm lint        # tsc --noEmit across packages

Run the docs site locally

pnpm docs                          # opens http://localhost:3000
# or, from inside apps/docs-next:
pnpm dev

The legacy Docusaurus site is still available during the migration:

pnpm docs:legacy

Repo layout

agentskit/
  packages/         — published packages (@agentskit/core, /react, /ink, …)
  apps/             — example apps + docs sites (not published)
  docs/architecture/adrs/   — formal contract decisions
  rfcs/             — design proposals under discussion
  tests/            — cross-package E2E (Playwright)
  .changeset/       — pending version bumps
  .github/          — workflows, issue templates, CODEOWNERS

Every package has a focused CONVENTIONS.md at its root explaining what belongs there, what doesn't, and how to add a new thing. Read it before opening a PR that touches that package.

Making a change

1. Pick or open an issue

Don't surprise reviewers. Either:

Pick an open issue (look for good first issue or help wanted), comment that you're taking it.
Browse the public project board — anything in Ready is fair game to claim.
Or open a new issue describing what you want to do before writing code, especially if the change touches a contract or a public API.

2. Branch and write code

git checkout main && git pull
git checkout -b your-name/short-description

Branch naming is informal but area/short-slug (e.g. adapters/add-mistral, docs/typos-in-recipes) helps scanning.

3. Write tests first when possible

Each package has a vitest.config.ts with a per-package coverage threshold. CI blocks merges that drop below the threshold (see docs/STABILITY.md and the coverage workflow). A new feature without a test will not pass review.

pnpm --filter @agentskit/core test            # run one package's tests
pnpm --filter @agentskit/core test:coverage   # with coverage report

4. Type-check, gates, and bundle-check

pnpm check:quality-gates                       # structural gates (fast)
pnpm --filter @agentskit/core lint            # tsc --noEmit
pnpm size                                      # all packages, gzipped

pnpm check:quality-gates runs every structural gate (typed errors, named exports, no any, file-size budgets, src↔test parity, for-agents coverage, ADR/RFC index sync, locale parity). pnpm check:all adds typecheck + build + test. A husky pre-push hook runs gates + typecheck + build automatically.

@agentskit/core is capped at 10KB gzipped by Manifesto principle 1. The size workflow blocks PRs that exceed any package's budget.

5. Add a changeset (any user-facing change)

pnpm changeset

This walks you through which packages are affected and what kind of bump (patch / minor / major). The resulting .changeset/*.md file is part of your PR. The release workflow consumes it later.

A change is user-facing if it adds or modifies a public export, changes runtime behavior, or affects the docs surface a consumer reads.

6. Open a PR

Use the PR template — it auto-fills with the checklist we expect:

Title: <type>(<scope>): <imperative one-liner>. Examples:

feat(adapters): add Mistral provider
fix(core): handle empty message arrays in controller
docs(recipes): clarify cost guard recipe
test(e2e): cover keyboard shortcuts in example-react

7. Reviews and CODEOWNERS

Each package has owners listed in .github/CODEOWNERS. They're auto-requested for review. Most PRs need one approval from an owner. Contract changes (anything in docs/architecture/adrs/) need two.

8. Merge

Maintainers merge with squash-and-merge by default, keeping the PR title as the squash commit message. Your branch is deleted automatically.

What requires an RFC vs a PR

Open an RFC before code if any of these are true:

A new package is being introduced
A breaking change to one of the six core contracts (Adapter, Tool, Memory, Retriever, Skill, Runtime)
A long-term tooling decision (build pipeline, theme system, deploy target)
A trade-off the reviewers will spend an hour debating

Open a PR directly for:

Bug fixes
New tools, skills, adapters, memory backends (governed by per-package CONVENTIONS.md)
Documentation (typos to whole pages)
Internal refactors that keep public APIs stable
Test additions

If you're unsure, open an issue first and ask.

Code style

The short version (full rules in CLAUDE.md and per-package CONVENTIONS.md):

TypeScript strict everywhere. No any — use unknown and narrow.
Named exports only. No default exports.
Tree-shakeable by default. Prefer multiple small exports over one big object.
No barrel files in publishable packages beyond the top-level src/index.ts.
Components are headless. Use data-ak-* attributes for styling hooks; don't hardcode colors.
Tools name with snake_case (matches every major provider). Match the regex ^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$.

Tests

Unit tests: vitest, run with pnpm test.
Coverage gate: per-package thresholds in each vitest.config.ts.
E2E: Playwright, run with pnpm test:e2e. Covers the four example apps.
Bundle size: size-limit, run with pnpm size.

CI runs all of these on every PR. Run them locally first to avoid burning CI minutes.

Documentation

If your change affects what a consumer sees or does:

Update the relevant page in apps/docs-next/content/docs/
Add a recipe if you've added a new building block (apps/docs-next/content/docs/recipes/)
Update the relevant ADR if you've changed how a contract behaves (rare — usually a new ADR superseding the old one)
Update the package's README.md if its public surface changed

Releases

Maintainers tag releases with the Changesets Action. Your changeset gets consumed automatically.

For local experimentation: pnpm changeset version then pnpm changeset publish. Don't run the publish command unless you're a maintainer with npm access.

Rollback

A bad publish is rolled back by shipping a corrected version forward (npm discourages unpublish). For any release with consumer-visible risk, the maintainer records a short rollback note:

## v<X.Y.Z> Rollback

**Changes:** [consumer-visible changes in this release]
**Smoke tests:** [surfaces/flows to verify within N minutes — e.g. `agentskit chat`, a runtime `run()`, docs build]
**Procedure:** [exact steps — e.g. `npm dist-tag add @agentskit/<pkg>@<prev> latest`, or publish a patch reverting the change]
**Authority:** [who can trigger; under what condition]
**Comms:** [who tells users; via which channel]

Semver intent: patch = internal fix, no API change; minor = additive (new export/option with a default); major = breaking, requires an RFC + migration notes.

Open a Discussion — somebody usually responds within a day
Check CLAUDE.md for project-specific patterns
Read the Manifesto when something feels wrong — it usually answers "why is it this way?"