# Building AgenticKit: Architecture, Workflows, and Lessons

> How AgenticKit is built: the Cursor context graph, CURSOR.md sync, CLI kits, and the lessons from packaging 34 agents as a product.

Canonical: https://www.agentickit.co/blog/building-agentickit-architecture-lessons
Last updated: 2026-08-14

The hard part was not writing 34 prompts. It was making them share one project truth and stay out of each other's way.

AgenticKit is a packaged context graph: agents point at skills, commands point at agents, rules are the floor, `CURSOR.md` is live world state. This is how that graph is built, how we use it on the product itself, and what I would change.

## The takeaway

A Cursor kit is not a chatbot with a roster. It is files that load in a known order, plus a CLI that installs them without clobbering the human-owned parts of `CURSOR.md`.

Steal the pattern or install the kit. Both are valid.

## What AgenticKit is, precisely

After `npx agentickit-cursor init` a repo gets:

- `.cursor/agents/*.md` (up to 34, depending on kit)
- `.cursor/skills/*/SKILL.md` (up to 49)
- `.cursor/commands/*.md` (up to 35)
- `.cursor/rules/*.mdc` (engineering, marketing, or both)
- `.cursor/hooks.json` plus a sync script
- `CURSOR.md` and `AGENTS.md` at the root

The npm package name is `agentickit-cursor` (npm blocks unscoped `agentickit`). The binary is `agentickit`. License check happens on `init` / `update`. That is the product. The website is a catalog of the same files.

It is not an autonomous company. It is not a hosted agent runtime. It is not a substitute for reading the diff.

## Architecture

```text
kit/template/          # source of truth for files that get copied
  .cursor/agents|
        /commands|
        /rules|
        /skills|
        /hooks
  CURSOR.md
  CURSOR.example.md
  AGENTS.md
  AGENTS.engineering.md
  AGENTS.marketing.md

lib/kit-manifest.js    # which files belong to engineering vs marketing vs both
lib/sync-cursor-md.js  # scan package.json (and friends), merge into CURSOR.md
bin/agentickit.js      # login, init, sync, watch, update, scan

site/                  # Next.js catalog: /agents /skills /commands /tools /blog
```

Kits are a manifest, not three copies of the repo. Marketing agents, commands, skills, and rules are a named list. Everything else in the template is engineering. `--kit both` is the union. `--kit marketing` still installs `shipkit-core` so the floor exists.

The site's `lib/agents.ts`, `lib/skills.ts`, and `lib/commands.ts` are the public catalog. If a playbook is not in the template, it should not be on the site. When those drift, that is a product bug.

## The context graph

```text
CURSOR.md          live world state (stack, scripts, skips, priorities)
    ^
    |  always-on rule says "read this first"
    |
.cursor/rules      constraints (error shape, tenant, globs)
    |
    +--> agents    roles (invoke / do-not, required skills)
            |
            +--> skills    procedures (how to do Stripe, Drizzle, RSC)
    |
    +--> commands  entry points (/ship adopts roles in order)
```

A command that does not name skills will improvise. An agent that does not name skills is a personality. A rule that repeats a skill is wasted tokens. The graph is how we keep those from happening.

[How the 34 agents are structured](/blog/how-i-structured-34-ai-agents) is the org chart. [The 35 commands](/blog/cursor-slash-commands-i-use) are the entry points. [The memory setup](/blog/cursor-memory-bank-setup) is `CURSOR.md` plus the hook.

## CURSOR.md as runtime config

`init`, `sync`, `watch`, `scan`, and a `sessionStart` hook all run the same merge:

- Infer stack from `package.json`, lockfiles, Drizzle/Prisma/Firebase/Go markers
- Write inferred rows into `CURSOR.md`
- Do not overwrite filled product fields (name, one-liner, tenant, what not to do)

That merge is the difference between a template and a living file. Without it, every install goes stale the first time you add Playwright.

Skip flags in `CURSOR.md` are more useful than a clever prompt. `/ship` honors Skip DB / UI / E2E / AI / Mobile. Those flags have saved more tokens than any system prompt tweak.

## Workflows we dogfood

The marketing site and the kit are a SaaS-shaped repo. The same OS applies.

- Engineering changes go through the [shipping pipeline](/blog/cursor-workflow-shipping-saas) or a focused `/fix`
- This blog series is the long-form version of what `/blog-post` is *for*, written by a human on purpose
- Launch artifacts, when we use them, belong under `docs/marketing/`
- Published pages get re-audited against real Search Console data, not just written once — see [the 4 fixes from our own page audit](/blog/search-console-page-audit-fixes)

We do not run `/ship` on a CSS token. We do not run `/launch` from the chat that just touched `kit-manifest.js`. That is the [Cursor vs Claude Code](/blog/cursor-vs-claude-code) point in kit form: one harness, two chats, shared `CURSOR.md`.

## Lessons

**Always-on rules must stay short.** The core rule is "read `CURSOR.md`, keep the error shape, tenant from session, end with files / test / next." Everything else is a glob or a skill. Fat always-on files were [failure 2](/blog/first-ai-coding-workflow-mistakes).

**The planner must not implement.** `tech-lead` produces a task table. The moment it writes the route, you do not have a plan. You have a first draft with extra headings.

**The writer must not self-approve.** Reviewer and security-auditor are separate. PASS/FAIL is a better interface than "looks good."

**Skip flags beat clever prompts.** An agent told to "only touch the API" will still open a page. A checked Skip UI is harder to ignore when the command text says to honor it.

**Programmatic pages are only as good as the playbooks.** 34 agent URLs do not help if the markdown behind them is a tagline. The site is a catalog. The template is the product.

**Marketing and engineering must not share a brain.** Two kits. Two chats. One `CURSOR.md` for product truth.

**Packaging is the job.** People can write these files themselves. They do not, because the graph is annoying to keep consistent. The CLI exists so the graph stays consistent.

## What I would change next

- Fewer overlapping operate roles for people on Vercel-only apps
- A thinner "starter" kit: core rule, `CURSOR.md`, `/ship`, `/fix`, `/audit`, five agents
- Better tests that the site catalog and the template cannot drift
- An honest path for teams that already have `AGENTS.md` and do not want 34 files

## Limitations

This remains Cursor-shaped. `AGENTS.md` is the portable floor. The interesting parts (globs, hooks, slash commands) are native.

It will not run your company. The [solo founder OS](/blog/cursor-solo-founders-idea-to-production) still needs a human who can reject a diff and talk to a user.

If you want the files, the [docs](/docs) install them. If you want the pattern, copy the graph at the top of this article into your own repo and stop at five agents. The graph is the lesson. The number 34 is just how far I pushed it.


## Related
- [kit-picker](https://www.agentickit.co/tools/kit-picker)
- [agent-chain](https://www.agentickit.co/tools/agent-chain)
- [tech-lead](https://www.agentickit.co/agents/tech-lead)
- [project-conventions](https://www.agentickit.co/skills/project-conventions)
- [saas-patterns](https://www.agentickit.co/skills/saas-patterns)
- [/ship](https://www.agentickit.co/commands/ship)
