Quick start — ap-sdk

1. Define a plugin

Start with a working scaffold:

npx ap-sdk init my-plugin

That writes a plugin.ts you can edit. Or create plugin.ts yourself and default-export the result of definePlugin:

plugin.ts

import {
  definePlugin,
  defineSkill,
  defineCommand,
} from "@jalco/ap-sdk";

export default definePlugin({
  id: "git-helper",
  description: "Helpers for working with git in a repo.",
  instructions: "## Git\n- Branch off main; never commit to it directly.",
  skills: [
    defineSkill({
      name: "diff-review",
      description:
        "Summarize and risk-flag uncommitted changes. Use when the user asks what changed.",
      instructions: "Run `git diff HEAD` and summarize the changes in 2-4 bullets.",
    }),
  ],
  commands: [
    defineCommand({
      name: "commit",
      description: "Write a conventional commit for the staged changes.",
      body: "Write a Conventional Commit message for the staged diff. Args: $ARGUMENTS",
    }),
  ],
});

2. Validate it

npx ap-sdk check

Invalid definitions report every problem at once via PluginValidationError, so you can fix them in one pass.

3. Build the native artifacts

npx ap-sdk build

This writes a tree per target under .aps-out/:

text

.aps-out/
├─ claude/      .claude-plugin/plugin.json, CLAUDE.md, skills/…, commands/…
├─ gemini/      gemini-extension.json, GEMINI.md, skills/…, commands/*.toml
├─ copilot/     .github/copilot-instructions.md, .github/prompts/*.prompt.md, …
└─ …            one tree per harness you targeted

Target a subset with -t:

npx ap-sdk build -t claude,gemini,cursor

4. Try it locally

install drops the artifacts straight into your project's local harness dirs (.claude/, .gemini/, .cursor/, …) so you can open the harness and use them:

npx ap-sdk install -t claude

For an edit/build/install loop while authoring, run watch mode:

npx ap-sdk dev --install -t claude

Add --global to install into your home-directory harness dirs, or --dry-run to preview without writing. See Installing a plugin for the full install model.

Next steps

Installing a plugin

Supported harnesses