# Contribute > | - **Type:** Skill - **Install:** `agentstack add skill-hec-ovi-agentickit-contribute` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hec-ovi](https://agentstack.voostack.com/s/hec-ovi) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hec-ovi](https://github.com/hec-ovi) - **Source:** https://github.com/hec-ovi/agentickit/tree/main/.pilot/skills/contribute ## Install ```sh agentstack add skill-hec-ovi-agentickit-contribute ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Contribute ## Contract By the end of this skill a contributor has: - A change localized to the right file under `packages/agentickit/src/`. - A matching test under the same package. - Updated public docs: both READMEs when the surface changes, plus the relevant `.pilot/skills/*` if the procedure for consumers shifts. - A green `pnpm --filter @hec-ovi/agentickit build` and `pnpm --filter agentickit test`. - A commit message matching `conventions/commit-style.md`. - Awareness of the rough size budget. The tree is ~5 kLoC today. A PR that adds 500 net lines is a red flag worth justifying; a PR that shrinks is a celebration. ## Iron Law: the public surface is the four hooks + two components + handler The entire external API is: - `usePilotState`, `usePilotAction`, `usePilotForm` - ``, ``, `` - `createPilotHandler`, `loadPilotProtocol`, `autoDetectModel` (server) - `parseResolver`, `parseSkill` (protocol) - `agentickit` CLI (`init`, `add-skill`) Adding to this surface is a deliberate choice with ecosystem consequences. **Every new export is a promise you'll maintain it. Shrink before you grow; refactor before you add.** ## Phases ### Phase 1: scope the change Before editing, write down in one paragraph: - What the change enables that wasn't possible before. - Whether it extends the public surface (new export) or refines an internal (same surface, different behavior). - What file(s) will change. - What test(s) will change. - What doc sections will change. If that paragraph is vague, the change isn't ready to code. ### Phase 2: find the right file The layout under `packages/agentickit/src/` is narrow on purpose: | Concern | File | |---------|------| | Public exports | `index.ts` | | Client-side types | `types.ts` | | React contexts | `context.ts` | | Dev-mode helpers | `env.ts` | | A hook | `hooks/use-pilot-*.ts` | | The provider | `components/pilot-provider.tsx` | | The sidebar (split) | `components/pilot-sidebar*.tsx` | | The server handler | `server/handler.ts` | | Server entry point | `server/index.ts` | | `.pilot/` parsing | `protocol/resolver.ts`, `protocol/skill.ts`, `protocol/manifest.ts` | Prefer editing an existing file over creating a new one. Every new file is a new boundary someone has to reason about. ### Phase 3: write the test first Vitest + happy-dom. Tests live adjacent to source (or under a `__tests__/` sibling if preferred). Run locally with `pnpm --filter @hec-ovi/agentickit test:watch`. Test shape we want: - Happy path (canonical usage). - Edge case (empty input, cleanup on unmount, two registrations). - Failure mode (invalid schema, missing provider context). ### Phase 4: implement Match the existing style: - Opinionated TypeScript, no `any`. - Comments describe *why*, not *what*. - Zod at trust boundaries. - Refs for volatile values to avoid thrashing registrations (see `use-pilot-action.ts` lines 57-64 for the canonical pattern). - Dev-mode warnings for misuse (see `isDev()` in `env.ts` and usage throughout the hooks). ### Phase 5: update docs when the surface moves When you change the public surface, update in this order: 1. `README.md` at the repo root (the narrative). 2. `packages/agentickit/README.md` (the npm description, often shorter). 3. `.pilot/skills/*/SKILL.md` for every skill whose procedure drifts. 4. Type exports in `packages/agentickit/src/index.ts` (and `server/index.ts`, `protocol/index.ts`). Skip steps 1-2 for internal refactors that don't change the surface. Always do (3); the skills are the agent-facing contract. ### Phase 6: validate ```bash pnpm --filter @hec-ovi/agentickit build pnpm --filter @hec-ovi/agentickit test pnpm --filter @agentickit-examples/todo dev # smoke test in the example ``` All three green. Then, and only then, stage and commit. ### Phase 7: commit and push Follow `.pilot/conventions/commit-style.md`. Quick template: ```bash git add packages/agentickit/src/hooks/use-pilot-action.ts \ packages/agentickit/src/hooks/__tests__/use-pilot-action.test.ts \ README.md \ packages/agentickit/README.md \ .pilot/skills/register-action/SKILL.md git commit -m "feat(hooks): " ``` Do NOT use `git add -A`. A stray `.env`, screenshot, or `node_modules` slipping in is a headache. ### Phase 8: size check Current package source (including CSS-in-JS + the CLI) sits at about 5 kLoC. After a change, eyeball the delta with: ```bash cloc packages/agentickit/src # or any line-counter ``` If a PR is adding a lot, ask: is there an existing file that shrinks? A comment that's too long? A helper that could be inlined? The "readable in an afternoon" promise is worth protecting. ## Anti-Patterns - Adding a new peer dependency casually. Every peer is a prompt for consumers to `npm install` something. The bar is high. - Introducing a wrapper around an AI SDK type that just re-exports it. Consumers can import from `ai` directly. - Writing docs before the code exists. READMEs lie when they describe vapor features. Ship the code first, then document it. - Fixing a bug in the example and not in the package. The example is consumer code; the source of truth lives under `packages/agentickit/src/`. - Editing `dist/`. It's generated. ## Output Format After contributing, report: - The change summary (1 sentence). - The files touched (paths). - Test coverage added (which test file + how many cases). - Doc sections updated. - LoC delta for the package. - Proof that `build` and `test` are green. ## Tools Used - `pnpm --filter @hec-ovi/agentickit build / test / test:watch`. - Edit source, test, and doc files. - `git add `, `git commit -m`. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hec-ovi](https://github.com/hec-ovi) - **Source:** [hec-ovi/agentickit](https://github.com/hec-ovi/agentickit) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-hec-ovi-agentickit-contribute - Seller: https://agentstack.voostack.com/s/hec-ovi - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.