feat(better-auth): add use-better-auth workflow skill

[amondnet]

Summary

Adds a hand-written use-better-auth workflow skill to the better-auth plugin, mirroring the structure and intent of Vercel's use-ai-sdk skill.

What was added and where

• New skill: plugins/better-auth/.agents/skills/use-better-auth/SKILL.md (216 lines, imperative voice, no second-person)
• Reference docs (4 files under .../references/):
  • adapters.md — supported framework adapters
  • plugins.md — built-in plugin catalogue
  • databases.md — supported database adapters
  • common-errors.md — common error patterns and fixes
• Version bump: plugins/better-auth/.claude-plugin/plugin.json 1.1.0 → 1.2.0
• Changelog: 1.2.0 entry prepended to plugins/better-auth/CHANGELOG.md

Why hand-written instead of vendor-synced

This skill is a meta-skill that teaches agents how to work with better-auth, not end-user best-practices that belong upstream in the better-auth source repository. Specifically:

• It mirrors the use-ai-sdk pattern from the Vercel plugin: ground every code-generation step in the installed package version by querying $(ask src better-auth) rather than trusting training-data knowledge that may be months behind the latest release.
• Vendor-synced skills (those with SYNC.md) are generated from upstream Gemini CLI extensions. There is no upstream source for this grounding skill — it was authored here intentionally.
• Placing it in .agents/skills/ (not skills/) keeps it out of the auto-sync pipeline and avoids accidental overwrites on the next bun run skills:sync.

Verification

• claude plugin validate plugins/better-auth passes with version 1.2.0.
• Plugin, adapter, and integration names in the reference files were spot-checked against $(ask src better-auth) source tree (e.g. betterAuth, prismaAdapter, twoFactor, admin).
• SKILL.md body is written in imperative mood with no second-person ("you") references, consistent with skill authoring standards.
• skills-lock.json was intentionally left untouched — it is managed exclusively by bunx skills add / vendor sync.

---

Summary by cubic

Adds a hand-written use-better-auth workflow skill to the better-auth plugin to ground auth work in the installed package version via the ask CLI. Mirrors the use-ai-sdk pattern to provide accurate, version-aware guidance.

• New Features

  • Added plugins/better-auth/.agents/skills/use-better-auth/SKILL.md that queries local better-auth source to avoid stale APIs.
  • Included references/ for adapters, plugins, databases, and common errors sourced from the repo.
  • Placed the skill under .agents/skills/ to stay out of the vendor sync pipeline.

• Dependencies

  • Bumped plugin version to 1.2.0 and updated CHANGELOG.md.

^{Written for commit 404540d. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
claude-code-plugins	Ready	Preview, Comment	Apr 23, 2026 6:14am

[cubic-dev-ai]

No issues found across 7 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

Architecture diagram

sequenceDiagram
    participant Agent as Agent (Claude)
    participant CLI as ask CLI
    participant FS as Local Source Code ($SRC)
    participant Ref as Reference Docs (NEW)
    participant App as App Code (Server/Client)
    participant DB as Database

    Note over Agent,Ref: Grounding Phase (NEW: use-better-auth skill)

    Agent->>CLI: NEW: Get source path via "ask src better-auth"
    CLI-->>Agent: Local path to library source
    
    Agent->>FS: NEW: Enumerate plugins & adapters in $SRC
    Note right of FS: Validates real exports instead of<br/>relying on stale training data
    FS-->>Agent: Directory structure / index exports

    Agent->>Ref: NEW: Consult reference/adapters.md
    Ref-->>Agent: Framework-specific mounting logic

    Note over Agent,App: Implementation Phase

    Agent->>App: NEW: Generate auth.ts with verified plugins
    Agent->>App: NEW: Generate framework-specific client (e.g. better-auth/react)
    
    opt Schema Synchronization
        Agent->>CLI: Run "npx auth generate"
        CLI->>DB: Inspect/Diff database schema
        DB-->>Agent: Schema drift status
    end

    alt Runtime/Type Error
        Agent->>Ref: NEW: Check common-errors.md for symptom
        Ref-->>Agent: Canonical fix (e.g. Secret strength, CORS)
        Agent->>App: CHANGED: Apply version-aware fix
    else Success
        Agent-->>Agent: Finalize workflow
    end

Loading

[gemini-code-assist]

Code Review

This pull request introduces a new use-better-auth skill to the better-auth plugin, providing comprehensive documentation and reference guides for framework adapters, common errors, database configurations, and built-in plugins. It also bumps the plugin version to 1.2.0. However, the placement of the new skill files in the .agents/skills/ directory violates the repository's style guide, as this directory is reserved for externally managed skills and should not be modified directly when a skills-lock.json file is present.