postkitstack · Yasirunet · Aug 11, 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
@@ -370,10 +370,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/
@@ -409,19 +409,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.
@@ -440,7 +445,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
 ---
@@ -453,7 +458,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
@@ -462,6 +467,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).
@@ -486,6 +513,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
@@ -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
 - **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
@@ -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
 - **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.json b/cli/package.json
@@ -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/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

diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
@@ -48,8 +48,8 @@ npm install -g @appritech/postkit
 
 ```bash
 # Clone the repository
-git clone https://github.com/appritechnologies/postkit.git
-cd postkit/cli
+git clone https://github.com/postkitstack/Postkit.git
+cd Postkit/cli
 
 # Install dependencies
 npm install

diff --git a/docs/docs/modules/db/troubleshooting.md b/docs/docs/modules/db/troubleshooting.md
@@ -102,4 +102,4 @@ The container ID is stored in `.postkit/db/session.json` under `containerID` if
 
 ## Getting Help
 
-If you're still stuck, please open an issue on [GitHub](https://github.com/appritechnologies/postkit/issues).
+If you're still stuck, please open an issue on [GitHub](https://github.com/postkitstack/Postkit/issues).
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -22,8 +22,8 @@ const config: Config = {
 
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
-  organizationName: 'appritechnologies', // Usually your GitHub org/user name.
-  projectName: 'postkit', // Usually your repo name.
+  organizationName: 'postkitstack', // Usually your GitHub org/user name.
+  projectName: 'Postkit', // Usually your repo name.
 
   onBrokenLinks: 'throw',
 
@@ -57,7 +57,7 @@ const config: Config = {
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
-            'https://github.com/appritechnologies/postkit/edit/main/docs/',
+            'https://github.com/postkitstack/Postkit/edit/main/docs/',
         },
         blog: {
           showReadingTime: true,
@@ -68,7 +68,7 @@ const config: Config = {
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl:
-            'https://github.com/appritechnologies/postkit/edit/main/docs/',
+            'https://github.com/postkitstack/Postkit/edit/main/docs/',
           // Useful options to enforce blogging best practices
           onInlineTags: 'warn',
           onInlineAuthors: 'warn',
@@ -106,7 +106,7 @@ const config: Config = {
           position: 'left',
         },
         {
-          href: 'https://github.com/appritechnologies/postkit',
+          href: 'https://github.com/postkitstack/Postkit',
           label: 'GitHub',
           position: 'right',
         },
@@ -137,7 +137,7 @@ const config: Config = {
           items: [
             {
               label: 'GitHub',
-              href: 'https://github.com/appritechnologies/postkit',
+              href: 'https://github.com/postkitstack/Postkit',
             },
             {
               label: 'Documentation',

diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx
@@ -35,7 +35,7 @@ function HomepageHero() {
           </Link>
           <Link
             className="button button--outline button--lg"
-            to="https://github.com/appritechnologies/postkit"
+            to="https://github.com/postkitstack/Postkit"
             target="_blank">
             GitHub
           </Link>

diff --git a/agent/skills/postkit-auth/SKILL.md → skills/postkit-auth/SKILL.md b/agent/skills/postkit-auth/SKILL.md → skills/postkit-auth/SKILL.md
diff --git a/agent/skills/postkit-migrate/SKILL.md → skills/postkit-migrate/SKILL.md b/agent/skills/postkit-migrate/SKILL.md → skills/postkit-migrate/SKILL.md
diff --git a/agent/skills/postkit-schema/SKILL.md → skills/postkit-schema/SKILL.md b/agent/skills/postkit-schema/SKILL.md → skills/postkit-schema/SKILL.md
diff --git a/agent/skills/postkit-setup/SKILL.md → skills/postkit-setup/SKILL.md b/agent/skills/postkit-setup/SKILL.md → skills/postkit-setup/SKILL.md
Original file line number	Diff line number	Diff line change
Expand Up		@@ -102,4 +102,4 @@ The container ID is stored in `.postkit/db/session.json` under `containerID` if

		## Getting Help

		If you're still stuck, please open an issue on [GitHub](https://github.com/appritechnologies/postkit/issues).
		If you're still stuck, please open an issue on [GitHub](https://github.com/postkitstack/Postkit/issues).