chore: add commandkit skills

Author: twlite

AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+This file is the operational guide for coding agents working in the
+CommandKit monorepo.
+
+## Repository layout
+
+- Monorepo managed with `pnpm` workspaces + Turborepo.
+- Workspace roots:
+  - `packages/*` - published/core packages
+  - `apps/*` - first-party apps (docs site, test bot, etc.)
+- Key project used as real-world reference:
+  - `apps/test-bot` - practical CommandKit usage patterns (plugins,
+    JSX components, tasks, workflow, ratelimit, i18n, sharding manager
+    pattern)
+
+## First source of truth for agents
+
+Use the skills in `skills/` first, then confirm with code and docs.
+
+- Skills index: `skills/README.md`
+- Core framework skill: `skills/commandkit/SKILL.md`
+- Plugin development skill:
+  `skills/commandkit-plugin-development/SKILL.md`
+
+Each skill includes:
+
+- `SKILL.md` with activation guidance and reference/tool tables
+- `references/*.md` with implementation details and best practices
+- optional `tools/*.mjs` helper generators/validators
+
+## CommandKit conventions to preserve
+
+When editing CommandKit projects (especially `apps/test-bot`),
+preserve convention-based discovery:
+
+- Config file at root: `commandkit.config.ts` (or `.js`)
+- App entrypoint: `src/app.ts` (exports discord.js client)
+- Commands: `src/app/commands/**`
+- Events: `src/app/events/**`
+- Optional feature paths:
+  - i18n: `src/app/locales/**`
+  - tasks: `src/app/tasks/**`
+  - workflow: `src/workflows/**`
+  - ratelimit runtime config: `ratelimit.ts`
+  - sharding manager: `src/sharding-manager.ts`
+
+Important middleware naming conventions:
+
+- `+global-middleware.ts`
+- `+middleware.ts`
+- `+<command>.middleware.ts`
+
+## Preferred implementation workflow
+
+1. Identify the target package/app and relevant skill in `skills/`.
+2. Read the corresponding `references/*.md` for exact patterns.
+3. Mirror existing local conventions (from nearby files) before
+   introducing new structures.
+4. Make minimal, focused changes.
+5. Validate with the appropriate command(s).
+
+## Validation commands
+
+From repo root:
+
+- Install deps: `pnpm install`
+- Build packages: `pnpm build`
+- Type-check packages: `pnpm check-types`
+- Format codebase: `pnpm format`
+- Check formatting only: `pnpm prettier:check`
+
+For app-level verification (example test bot):
+
+- `pnpm --filter test-bot dev`
+- `pnpm --filter test-bot build`
+- `pnpm --filter test-bot start`
+
+## Documentation and guide alignment
+
+When adding or changing behavior, keep docs alignment in mind:
+
+- Guide docs: `apps/website/docs/guide/**`
+- API reference docs: `apps/website/docs/api-reference/**`
+
+If you add new user-facing behavior in packages, update the relevant
+guide and/or API reference pages.
+
+## Plugin development guidance
+
+For creating CommandKit plugins:
+
+- Runtime plugin patterns:
+  `skills/commandkit-plugin-development/references/01-runtime-plugin-basics.md`
+- Runtime hook mapping:
+  `skills/commandkit-plugin-development/references/02-runtime-hooks-reference.md`
+- Compiler transforms:
+  `skills/commandkit-plugin-development/references/03-compiler-plugin-transform.md`
+- Template extension hooks:
+  `skills/commandkit-plugin-development/references/04-template-registration.md`
+- Rolldown integration:
+  `skills/commandkit-plugin-development/references/05-rolldown-plugins.md`
+
+## Safety and quality rules
+
+- Do not introduce APIs that are not already present in the
+  codebase/docs unless explicitly asked.
+- Do not break convention-based file discovery paths.
+- Keep changes backward-compatible unless the task explicitly requires
+  a breaking change.
+- Prefer explicit error handling in runtime hooks and long-running
+  workflows.
+- For interactive JSX components, use valid interaction patterns
+  (`onClick` for interactive buttons, link buttons with `url` +
+  `ButtonStyle.Link`).
+
+## Git hygiene
+
+- Do not revert unrelated user changes.
+- Keep commits scoped and descriptive when asked to commit.
+- Avoid destructive git operations unless explicitly requested.

skills/README.md

@@ -0,0 +1,44 @@
+# CommandKit Skills Index
+
+This directory contains self-contained skills for public CommandKit
+packages and development workflows.
+
+Each skill folder includes:
+
+- `SKILL.md` for activation and execution behavior
+- `README.md` for human-facing scope and usage notes
+- `references/*.md` for feature-specific snippets, filesystem
+  expectations, important details, and best practices
+- optional `tools/*.mjs` JavaScript helpers with shebang for
+  repeatable utility tasks
+
+`SKILL.md` files include tabular indexes for references and tools,
+with name + description columns.
+
+## Included skills
+
+- `skills/commandkit`
+- `skills/create-commandkit`
+- `skills/commandkit-ai`
+- `skills/commandkit-analytics`
+- `skills/commandkit-cache`
+- `skills/commandkit-devtools`
+- `skills/commandkit-i18n`
+- `skills/commandkit-legacy-migration`
+- `skills/commandkit-queue`
+- `skills/commandkit-ratelimit`
+- `skills/commandkit-redis`
+- `skills/commandkit-tasks`
+- `skills/commandkit-workflow`
+- `skills/commandkit-plugin-development`
+
+## Excluded internal packages
+
+- `@commandkit/devtools-ui` (private internal UI package)
+- `tsconfig` (private internal tooling package)
+
+## Legacy policy
+
+`@commandkit/legacy` is represented only by a migration-focused skill.
+It should be used to move existing projects to modern CommandKit
+patterns, not to encourage new legacy adoption.

skills/commandkit-ai/README.md

@@ -0,0 +1,22 @@
+# commandkit-ai skill
+
+Specialized skill for implementing AI features with `@commandkit/ai`.
+
+## Use this skill when
+
+- enabling AI plugin support in CommandKit
+- building natural language command flows
+- registering/executing AI tools
+- debugging AI response or execution behavior
+
+## Typical inputs
+
+- target AI behavior
+- model/provider constraints
+- desired tool integration
+
+## Expected outputs
+
+- plugin/config updates
+- command-level implementation changes
+- practical error handling and fallback strategy

skills/commandkit-ai/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: commandkit-ai
+version: 1.2.0
+author: neplextech
+emoji: '🤖'
+tags:
+  - commandkit
+  - ai
+  - tools
+  - llm
+description: >
+  Build AI-powered command flows with @commandkit/ai. Use for model
+  selection, message filtering, schema-backed AI commands, and safe
+  tool-calling behavior.
+---
+
+# CommandKit AI Plugin
+
+## Activation guidance
+
+Use when implementing natural-language command execution or AI tool
+orchestration.
+
+## Required filesystem expectations
+
+- plugin registration in `commandkit.config.ts`
+- AI runtime config in `src/ai.ts` or `src/ai.js`
+- AI-enabled command files in `src/app/commands/**`
+
+## Execution workflow
+
+1. Register `ai()` plugin.
+2. Configure `configureAI()` in `src/ai.*`.
+3. Implement `aiConfig` schema and `ai` command handlers.
+4. Add tool registration and robust error handling.
+5. Validate trigger filter, permissions, and response safety.
+
+## Guardrails
+
+- Never hardcode API keys.
+- Treat AI output as untrusted input for sensitive operations.
+- Keep tool descriptions explicit and narrow.
+
+## Reference index
+
+| Name                                    | Description                                                    |
+| --------------------------------------- | -------------------------------------------------------------- |
+| `references/00-filesystem-structure.md` | File layout and export expectations for AI-enabled projects.   |
+| `references/01-plugin-setup.md`         | Minimal plugin wiring in config.                               |
+| `references/02-configure-ai-model.md`   | Model selection, message filters, and runtime option patterns. |
+| `references/03-ai-command-schema.md`    | Typed schema + AI command implementation pattern.              |
+| `references/04-custom-tools.md`         | Tool creation and safe exposure patterns.                      |
+
+## Tool index
+
+| Name                                     | Description                                                           |
+| ---------------------------------------- | --------------------------------------------------------------------- |
+| `tools/generate-ai-command-template.mjs` | Prints a starter AI command template with schema and handler exports. |

skills/commandkit-ai/references/00-filesystem-structure.md

@@ -0,0 +1,49 @@
+# 00 filesystem structure
+
+## Purpose
+
+Define required filesystem layout so feature discovery and runtime bootstrapping work reliably.
+
+## When to use
+
+Use when creating a new project, enabling a plugin, or debugging why files are not discovered.
+
+## Filesystem
+
+```txt
+project/
+  commandkit.config.ts
+  src/
+    ai.ts
+    app/
+      commands/
+```
+
+## Example
+
+```txt
+project/
+  commandkit.config.ts
+  src/
+    ai.ts
+    app/
+      commands/
+```
+
+## Important details
+
+- Use exact API/export names shown in the example.
+- Keep filesystem placement aligned with enabled plugins and feature expectations.
+- Preserve deterministic behavior and explicit error handling in implementation code.
+
+## Best practices
+
+- Keep snippets as baseline patterns and adapt them to real command names and data models.
+- Validate external inputs and permission boundaries before side effects.
+- Keep setup deterministic so startup behavior is stable across environments.
+
+## Common mistakes
+
+- Creating feature files in arbitrary folders not discovered by CommandKit.
+- Renaming key directories without matching framework conventions.
+- Missing root config file while expecting auto-discovery to work.

skills/commandkit-ai/references/01-plugin-setup.md

@@ -0,0 +1,49 @@
+# 01 plugin setup
+
+## Purpose
+
+Show minimal plugin registration pattern.
+
+## When to use
+
+Use when implementing or reviewing this feature in a CommandKit-based project.
+
+## Filesystem
+
+```txt
+project/
+  commandkit.config.ts
+  src/
+    ai.ts
+    app/
+      commands/
+```
+
+## Example
+
+```ts
+import { defineConfig } from 'commandkit';
+import { ai } from '@commandkit/ai';
+
+export default defineConfig({
+  plugins: [ai()],
+});
+```
+
+## Important details
+
+- Use exact API/export names shown in the example.
+- Keep filesystem placement aligned with enabled plugins and feature expectations.
+- Preserve deterministic behavior and explicit error handling in implementation code.
+
+## Best practices
+
+- Keep snippets as baseline patterns and adapt them to real command names and data models.
+- Validate external inputs and permission boundaries before side effects.
+- Keep setup deterministic so startup behavior is stable across environments.
+
+## Common mistakes
+
+- Skipping validation for user-provided inputs before side effects.
+- Changing structure/config without verifying companion files.
+- Copying snippets without adapting identifiers and environment values.