postkitstack · nipunappri · Aug 11, 2026 · Aug 28, 2026
diff --git a/.claude/skills/architecture/SKILL.md b/.claude/skills/architecture/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: architecture
 description: Review and propose system architecture decisions, generate ADRs.
+metadata:
+ internal: true
 ---
 
 # Architecture Skill

diff --git a/.claude/skills/bugfix/SKILL.md b/.claude/skills/bugfix/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: bugfix
-description: Diagnose and fix bugs with a 4-stage workflow: gather info, diagnose, fix, test, validate & review.
+description: "Diagnose and fix bugs with a 4-stage workflow: gather info, diagnose, fix, test, validate & review."
+metadata:
+ internal: true
 ---
 
 # Bugfix Skill

diff --git a/.claude/skills/create-feature/SKILL.md b/.claude/skills/create-feature/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: create-feature
-description: Implement new features end-to-end: gather info, plan, implement, test, validate, review.
+description: "Implement new features end-to-end: gather info, plan, implement, test, validate, review."
+metadata:
+ internal: true
 ---
 
 # Create Feature Skill

diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
@@ -3,6 +3,8 @@ name: create-pr
 description: Generate a PR description for the current branch and save it to temp/pr-description.md. Analyzes commits against the base branch and fills in the project PR template exactly.
 argument-hint: "[base-branch]"
 allowed-tools: Bash, Read, Write
+metadata:
+ internal: true
 ---
 
 # Create PR Skill

diff --git a/.claude/skills/update-docs/SKILL.md b/.claude/skills/update-docs/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: update-docs
 description: Update project documentation when code changes occur.
+metadata:
+ internal: true
 ---
 
 # Update Docs Skill

diff --git a/.claude/skills/write-test-e2e/SKILL.md b/.claude/skills/write-test-e2e/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: write-test-e2e
 description: Write end-to-end tests for PostKit CLI using testcontainers and black-box testing.
+metadata:
+ internal: true
 ---
 
 # Write E2E Tests Skill

diff --git a/.claude/skills/write-test-unit/SKILL.md b/.claude/skills/write-test-unit/SKILL.md
@@ -1,6 +1,8 @@
 ---
 name: write-test-unit
 description: Write unit tests for PostKit CLI using Vitest with proper mocking patterns.
+metadata:
+ internal: true
 ---
 
 # Write Unit Tests Skill

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -384,10 +384,10 @@ PostKit ships with Claude Code agent skills that teach AI assistants how to work
 
 ### Skill Anatomy
 
-Each skill lives in its own directory under `agent/skills/`:
+Each skill lives in its own directory under `skills/`:
 
 ```
-agent/skills/
+skills/
 ├── postkit-migrate/
 │ └── SKILL.md # Frontmatter (name, description, allowed-tools) + markdown instructions
 ├── postkit-setup/
@@ -423,19 +423,24 @@ Use the [skills CLI](https://github.com/vercel-labs/skills) to install PostKit s
 
 ```bash
 # Install all PostKit skills (interactive)
-npx skills add appritechnologies/Postkit
+npx skills add postkitstack/Postkit
 
 # List available skills first
-npx skills add appritechnologies/Postkit --list
+npx skills add postkitstack/Postkit --list
 
 # Install specific skills only
-npx skills add appritechnologies/Postkit --skill postkit-migrate --skill postkit-schema
+npx skills add postkitstack/Postkit --skill postkit-migrate --skill postkit-schema
 
 # Install for a specific agent (e.g., Claude Code)
-npx skills add appritechnologies/Postkit -a claude-code
-
-# Non-interactive (CI/CD friendly)
-npx skills add appritechnologies/Postkit --all -y
+npx skills add postkitstack/Postkit -a claude-code
+
+# Non-interactive (CI/CD friendly) — name each skill explicitly.
+# Avoid `--all`: it expands to every skill *and* every agent, and it
+# bypasses the internal-skill filter, so it also pulls PostKit's own
+# repo-maintenance skills into your project.
+npx skills add postkitstack/Postkit -y --agent claude-code \
+ --skill postkit-migrate --skill postkit-setup \
+ --skill postkit-schema --skill postkit-auth
 ```
 
 The CLI auto-detects which coding agents you have installed and places skills in the correct directory for each agent. By default, skills are symlinked (single source of truth, easy to update). Use `--copy` for independent copies.
@@ -454,7 +459,7 @@ npx skills update postkit-auth # Update a specific skill
 
 ### Adding a New Skill
 
-Create `agent/skills/<skill-name>/SKILL.md`:
+For a **public** skill (one PostKit users install), create `skills/<skill-name>/SKILL.md`. For internal contributor tooling, use `.claude/skills/` instead and read [Public vs Internal Skills](#public-vs-internal-skills) first.
 
 ```yaml
 ---
@@ -467,7 +472,7 @@ allowed-tools: Bash(postkit *)
 Skills can optionally include bundled resources for more complex workflows:
 
 ```
-agent/skills/<skill-name>/
+skills/<skill-name>/
 ├── SKILL.md # Required — skill instructions
 ├── scripts/ # Optional — executable scripts for repetitive tasks
 ├── references/ # Optional — reference docs loaded into context as needed
@@ -476,6 +481,28 @@ agent/skills/<skill-name>/
 
 When a skill grows beyond ~500 lines, split domain-specific content into `references/` files and point to them from SKILL.md.
 
+### Public vs Internal Skills
+
+Two kinds of skills live in this repo, and the split is load-bearing for packaging:
+
+| Location | Kind | Shipped by `npx skills add` |
+|----------|------|-----------------------------|
+| `skills/` | Public — for people *using* PostKit | Yes |
+| `.claude/skills/` | Internal — for people *developing* PostKit | No |
+
+`skills/` is a directory the skills CLI searches by default; `agent/skills/` is **not**, which is why public skills live at `skills/`.
+
+`.claude/skills/` is also a directory the CLI searches, so every internal skill must carry:
+
+```yaml
+metadata:
+ internal: true
+```
+
+Without it, contributor tooling (`/bugfix`, `/create-pr`, …) gets installed into end users' projects. The flag hides the skill from discovery, `--list`, and interactive install; Claude Code ignores the field and loads the skill locally as normal. Contributors can still fetch internal skills with `INSTALL_INTERNAL_SKILLS=1` or an explicit `--skill <name>`.
+
+Descriptions containing `: ` (colon-space) **must be quoted** — unquoted, YAML parses them as a nested mapping and the skills CLI skips the file with a parse error.
+
 ## Important Notes
 
 - All paths in `common/config.ts` are resolved relative to either `cliRoot` (the CLI installation) or `projectRoot` (where the user runs commands).
@@ -500,6 +527,8 @@ Skills are invoked via `/<skill-name>` in Claude Code. Agents are sub-processes
 
 ### Skills Registry
 
+These are **internal** skills — they live in `.claude/skills/` and must each carry `metadata: internal: true` so they are not shipped to end users. See [Public vs Internal Skills](#public-vs-internal-skills).
+
 | Skill | Invocation | Purpose | Sub-Agents |
 |-------|-----------|---------|------------|
 | create-pr | `/create-pr` | Generate PR description to `temp/pr-description.md` | — |

diff --git a/README.md b/README.md
@@ -22,15 +22,15 @@ PostKit brings together the following components:
 
 ## PostKit CLI
 
-The PostKit CLI (`@appritech/postkit`) is the developer toolkit for working with the PostKit stack. It provides safe database migrations, auth management, and project scaffolding.
+The PostKit CLI (`@postkitstack/postkit`) is the developer toolkit for working with the PostKit stack. It provides safe database migrations, auth management, and project scaffolding.
 
 **Documentation:** [https://docs.postkitstack.com/](https://docs.postkitstack.com/)
 
 ### Quick Start
 
 ```bash
 # Install the CLI
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 
 # Initialize a new project
 postkit init
@@ -81,15 +81,15 @@ No restart needed — Claude Code picks up changes automatically.
 
 Full documentation is available at [docs.postkitstack.com](https://docs.postkitstack.com/).
 
-For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/db/troubleshooting) or open an issue on [GitHub](https://github.com/appritechnologies/postkit/issues).
+For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/db/troubleshooting) or open an issue on [GitHub](https://github.com/postkitstack/Postkit/issues).
 
 ## Links
 
 - **CLI Tool**: [cli/README.md](cli/README.md)
-- **npm Package**: https://www.npmjs.com/package/@appritech/postkit
+- **npm Package**: https://www.npmjs.com/package/@postkitstack/postkit
 - **Documentation**: https://docs.postkitstack.com/
-- **GitHub**: https://github.com/appritechnologies/postkit
-- **Issues**: https://github.com/appritechnologies/postkit/issues
+- **GitHub**: https://github.com/postkitstack/Postkit
+- **Issues**: https://github.com/postkitstack/Postkit/issues
 
 ## License
 

diff --git a/cli/README.md b/cli/README.md
@@ -1,11 +1,11 @@
-# @appritech/postkit
+# @postkitstack/postkit
 
 > Developer toolkit for database migrations and backend automation
 
 **Note:** This tool is still under development and not recommended for production use. APIs may change between versions.
 
-[![npm version](https://badge.fury.io/js/@appritech/postkit.svg)](https://www.npmjs.com/package/@appritech/postkit)
-[![License](https://img.shields.io/npm/l/@appritech/postkit.svg)](LICENSE)
+[![npm version](https://badge.fury.io/js/@postkitstack/postkit.svg)](https://www.npmjs.com/package/@postkitstack/postkit)
+[![License](https://img.shields.io/npm/l/@postkitstack/postkit.svg)](LICENSE)
 
 PostKit CLI is a modular toolkit for backend development with the Appri stack. It provides safe database migrations, auth management, and more.
 
@@ -16,7 +16,7 @@ PostKit CLI is a modular toolkit for backend development with the Appri stack. I
 ### Installation
 
 ```bash
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 ```
 
 ### Requirements
@@ -186,14 +186,14 @@ postkit db commit
 postkit db deploy --remote staging
 ```
 
-For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/db/troubleshooting) or open an issue on [GitHub](https://github.com/appritechnologies/postkit/issues).
+For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/db/troubleshooting) or open an issue on [GitHub](https://github.com/postkitstack/Postkit/issues).
 
 ## 🔗 Links
 
-- **npm Package**: https://www.npmjs.com/package/@appritech/postkit
+- **npm Package**: https://www.npmjs.com/package/@postkitstack/postkit
 - **Documentation**: https://docs.postkitstack.com/
-- **GitHub**: https://github.com/appritechnologies/postkit
-- **Issues**: https://github.com/appritechnologies/postkit/issues
+- **GitHub**: https://github.com/postkitstack/Postkit
+- **Issues**: https://github.com/postkitstack/Postkit/issues
 
 ## 📜 License
 

diff --git a/cli/package-lock.json b/cli/package-lock.json
diff --git a/cli/package.json b/cli/package.json
@@ -1,5 +1,5 @@
 {
- "name": "@appritech/postkit",
+ "name": "@postkitstack/postkit",
  "version": "1.3.2",
  "description": "PostKit - Developer toolkit for database management and more",
  "type": "module",
@@ -46,11 +46,11 @@
  "license": "Apache-2.0",
  "repository": {
  "type": "git",
- "url": "https://github.com/appritechnologies/postkit.git"
+ "url": "https://github.com/postkitstack/Postkit.git"
  },
- "homepage": "https://github.com/appritechnologies/postkit#readme",
+ "homepage": "https://github.com/postkitstack/Postkit#readme",
  "bugs": {
- "url": "https://github.com/appritechnologies/postkit/issues"
+ "url": "https://github.com/postkitstack/Postkit/issues"
  },
  "dependencies": {
  "chalk": "^5.3.0",

diff --git a/docs/blog/2026-05-04-migrating-from-prisma.md b/docs/blog/2026-05-04-migrating-from-prisma.md
@@ -35,7 +35,7 @@ The transition has two phases: getting your current schema into PostKit, then sw
 PostKit's `db import` command reads your current PostgreSQL database (not your `schema.prisma`) and generates schema files:
 
 ```bash
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 postkit init
 
 # Add your database as a remote

diff --git a/docs/blog/2026-05-10-why-session-based-migrations.md b/docs/blog/2026-05-10-why-session-based-migrations.md
@@ -113,7 +113,7 @@ For databases where a full clone is impractical (100GB+), you can use a represen
 ## Getting Started
 
 ```bash
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 postkit init
 postkit db remote add prod "postgres://..." --default
 postkit db start # clone happens here

diff --git a/docs/blog/2026-05-12-migrating-from-supabase-to-postkit.md b/docs/blog/2026-05-12-migrating-from-supabase-to-postkit.md
@@ -31,7 +31,7 @@ PostKit does not replace Supabase's auth, storage, or realtime features. If you
 ## Step 1: Install PostKit
 
 ```bash
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 ```
 
 Verify:
@@ -205,7 +205,7 @@ If you have existing Supabase migration files (`.sql` files in `supabase/migrati
 
 | Step | Command |
 |------|---------|
-| Install PostKit | `npm install -g @appritech/postkit` |
+| Install PostKit | `npm install -g @postkitstack/postkit` |
 | Init project | `postkit init` |
 | Add Supabase remote | `postkit db remote add supabase "postgres://..."` |
 | Import existing schema | `postkit db import --url "postgres://..."` |

diff --git a/docs/blog/authors.yml b/docs/blog/authors.yml
@@ -1,5 +1,5 @@
 postkit_team:
  name: PostKit Team
  title: Appri Technologies
- url: https://github.com/appritechnologies
- image_url: https://github.com/appritechnologies.png
+ url: https://github.com/postkitstack
+ image_url: https://github.com/postkitstack.png
diff --git a/docs/docs/agent-skills/overview.md b/docs/docs/agent-skills/overview.md
@@ -21,30 +21,45 @@ Use the [skills CLI](https://github.com/vercel-labs/skills) to install PostKit s
 
 ```bash
 # Install all PostKit skills (interactive)
-npx skills add appritechnologies/Postkit
+npx skills add postkitstack/Postkit
 
 # List available skills first
-npx skills add appritechnologies/Postkit --list
+npx skills add postkitstack/Postkit --list
 
 # Install specific skills only
-npx skills add appritechnologies/Postkit --skill postkit-migrate --skill postkit-schema
+npx skills add postkitstack/Postkit --skill postkit-migrate --skill postkit-schema
 
 # Install for a specific agent (e.g., Claude Code)
-npx skills add appritechnologies/Postkit -a claude-code
-
-# Non-interactive (CI/CD friendly)
-npx skills add appritechnologies/Postkit --all -y
+npx skills add postkitstack/Postkit -a claude-code
+
+# Non-interactive (CI/CD friendly) — name each skill explicitly.
+# Avoid `--all`: it expands to every skill *and* every agent, and it
+# bypasses the internal-skill filter, so it also pulls PostKit's own
+# repo-maintenance skills into your project.
+npx skills add postkitstack/Postkit -y --agent claude-code \
+ --skill postkit-migrate --skill postkit-setup \
+ --skill postkit-schema --skill postkit-auth
 ```
 
 ### Scope
 
-| Scope | Flag | Location | Use Case |
-|-------|------|----------|----------|
-| **Project** (default) | | `./<agent>/skills/` | Committed with your project, shared with team |
-| **Global** | `-g` | `~/<agent>/skills/` | Available across all your projects |
+| Scope | Flag | Location (Claude Code) | Use Case |
+|-------|------|------------------------|----------|
+| **Project** (default) | | `./.claude/skills/` | Committed with your project, shared with team |
+| **Global** | `-g` | `~/.claude/skills/` | Available across all your projects |
+
+The exact directory depends on the agent. Claude Code uses `.claude/skills/`; Cursor, Codex, Cline, Gemini CLI, and GitHub Copilot share the standard `.agents/skills/`; Windsurf and Roo Code use `.windsurf/skills/` and `.roo/skills/`. The CLI picks the right one for each agent you install to.
 
 By default, skills are **symlinked** — a single source of truth that's easy to update. Use `--copy` for independent copies when symlinks aren't supported.
 
+### Verify the Install
+
+```bash
+npx skills list
+```
+
+You should see the four `postkit-*` skills. In Claude Code, `/postkit-migrate` and friends become available in new sessions.
+
 ### Update Skills
 
 ```bash