From 511d4d81a86f0c11fab66c0837bca42e6bce96fb Mon Sep 17 00:00:00 2001 From: Yasiru Geevinda Date: Tue, 11 Aug 2026 19:17:49 +0000 Subject: [PATCH] fix: issues on postkit skill, repo migration changes, minor docs --- .claude/skills/architecture/SKILL.md | 2 + .claude/skills/bugfix/SKILL.md | 4 +- .claude/skills/create-feature/SKILL.md | 4 +- .claude/skills/create-pr/SKILL.md | 2 + .claude/skills/update-docs/SKILL.md | 2 + .claude/skills/write-test-e2e/SKILL.md | 2 + .claude/skills/write-test-unit/SKILL.md | 2 + CLAUDE.md | 51 +++++++++++++++---- README.md | 6 +-- cli/README.md | 6 +-- cli/package.json | 6 +-- docs/docs/agent-skills/overview.md | 37 ++++++++++---- docs/docs/getting-started/installation.md | 4 +- docs/docs/modules/db/troubleshooting.md | 2 +- docs/docusaurus.config.ts | 12 ++--- docs/src/pages/index.tsx | 2 +- .../skills => skills}/postkit-auth/SKILL.md | 0 .../postkit-migrate/SKILL.md | 0 .../skills => skills}/postkit-schema/SKILL.md | 0 .../skills => skills}/postkit-setup/SKILL.md | 0 20 files changed, 101 insertions(+), 43 deletions(-) rename {agent/skills => skills}/postkit-auth/SKILL.md (100%) rename {agent/skills => skills}/postkit-migrate/SKILL.md (100%) rename {agent/skills => skills}/postkit-schema/SKILL.md (100%) rename {agent/skills => skills}/postkit-setup/SKILL.md (100%) diff --git a/.claude/skills/architecture/SKILL.md b/.claude/skills/architecture/SKILL.md index d0c60f2..2f2087c 100644 --- 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 index 4a787b7..7580346 100644 --- 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 index 3e6cea5..3fb793d 100644 --- 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 index 70a34ac..50f4649 100644 --- 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 index 052bca4..17a5fb6 100644 --- 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 index 8bb1be0..832033d 100644 --- 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 index 4f65ebf..6290d64 100644 --- 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 index 8d01b8b..d6c779e 100644 --- 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.md`: +For a **public** skill (one PostKit users install), create `skills//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// +skills// ├── 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// 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 `. + +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 `/` 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 index 0f7d4e6..22c14a9 100644 --- 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 index 1f5cc8a..aa43784 100644 --- 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 index cc60552..eb98dc1 100644 --- 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 index 500e6b6..4d945ad 100644 --- 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) | | `.//skills/` | Committed with your project, shared with team | -| **Global** | `-g` | `~//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 index bdb9dfb..0777dee 100644 --- 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 index 89c2112..ee8e2c1 100644 --- 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 index 1ebab87..8f2e4a6 100644 --- 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 index 9d54ae0..d0a011c 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -35,7 +35,7 @@ function HomepageHero() { GitHub diff --git a/agent/skills/postkit-auth/SKILL.md b/skills/postkit-auth/SKILL.md similarity index 100% rename from agent/skills/postkit-auth/SKILL.md rename to skills/postkit-auth/SKILL.md diff --git a/agent/skills/postkit-migrate/SKILL.md b/skills/postkit-migrate/SKILL.md similarity index 100% rename from agent/skills/postkit-migrate/SKILL.md rename to skills/postkit-migrate/SKILL.md diff --git a/agent/skills/postkit-schema/SKILL.md b/skills/postkit-schema/SKILL.md similarity index 100% rename from agent/skills/postkit-schema/SKILL.md rename to skills/postkit-schema/SKILL.md diff --git a/agent/skills/postkit-setup/SKILL.md b/skills/postkit-setup/SKILL.md similarity index 100% rename from agent/skills/postkit-setup/SKILL.md rename to skills/postkit-setup/SKILL.md