fix(plugins): move hand-written skills from .agents/skills/ to skills/

[amondnet]

Summary

Hand-written skills use-mastra (#161) and use-better-auth (#159) were committed to plugins/<name>/.agents/skills/, but per repo convention (see CLAUDE.md), that path is reserved for vendor-managed skills.sh-installed skills tracked in skills-lock.json (read-only, do not modify directly). Hand-written skills belong in the default plugins/<name>/skills/ location.

This PR relocates both skills and updates the skills field in each plugin.json to the array form ["./skills/", "./.agents/skills/"] so Claude Code loads from both locations (per the official plugin reference: a custom skills path replaces the default unless you opt back in via the array form).

Version bumps and CHANGELOG entries are intentionally not included — release-please owns both for plugins/* via release-please-config.json and will bump them automatically on the next chore: release main PR based on the fix(...) commits in this branch.

Changes

• plugins/mastra/
  • git mv .agents/skills/use-mastra → skills/use-mastra (4 files, pure rename)
  • plugin.json: "skills": "./.agents/skills/" → ["./skills/", "./.agents/skills/"]
• plugins/better-auth/
  • git mv .agents/skills/use-better-auth → skills/use-better-auth (5 files, pure rename)
  • plugin.json: same array change

What's NOT touched

• Vendor-managed skill dirs (mastra/ in mastra plugin; 5 best-practices dirs in better-auth) — left intact under .agents/skills/.
• skills-lock.json files — they only track vendor skills; hand-written skills are not registered there.
• Skill content (SKILL.md, references/*.md) — pure relocation, byte-identical.
• plugin.json version and CHANGELOG.md — release-please owns these.

Verification

$ claude plugin validate plugins/mastra/
✔ Validation passed

$ claude plugin validate plugins/better-auth/
✔ Validation passed

Related

• Refs feat(mastra): add use-mastra workflow skill #161 (introduced misplaced use-mastra)
• Refs feat(better-auth): add use-better-auth workflow skill #159 (introduced misplaced use-better-auth)

[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 29, 2026 5:09am

[cubic-dev-ai]

No issues found across 13 files

Confidence score: 5/5

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

Architecture diagram

sequenceDiagram
    participant CLI as Claude Code CLI
    participant Json as plugin.json
    participant DevDir as /skills/ (Developer)
    participant VendorDir as /.agents/skills/ (Vendor)
    participant Lock as skills-lock.json

    Note over CLI, Lock: Plugin Initialization & Skill Loading

    CLI->>Json: Read plugin manifest
    Json-->>CLI: CHANGED: skills: ["./skills/", "./.agents/skills/"]

    Note over CLI, DevDir: Stage 1: Load Author-Managed Skills
    CLI->>DevDir: NEW: Scan directory for hand-written skills
    Note right of DevDir: e.g. use-mastra, use-better-auth
    DevDir-->>CLI: Return skill definitions (SKILL.md + references)

    Note over CLI, VendorDir: Stage 2: Load Vendor-Managed Skills
    CLI->>VendorDir: Scan directory for automated skills
    
    opt Managed Path Validation
        CLI->>Lock: Check skills-lock.json
        Lock-->>CLI: Verified vendor skill list
    end
    
    VendorDir-->>CLI: Return framework-generated skill definitions

    CLI->>CLI: Merge and register all discovered skills
    Note over CLI: Skills from both paths available to Agent context

Loading

[gemini-code-assist]

Code Review

This pull request moves hand-written skills for the better-auth and mastra plugins from the .agents/skills/ directory to the skills/ directory to align with repository conventions. The plugin.json files for both plugins were updated to support multiple skill paths and the versions were incremented. Feedback was provided to include comparison links and maintain consistent date formatting in the CHANGELOG.md entries for both plugins.

[cubic-dev-ai]

2 issues found across 4 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="plugins/better-auth/.claude-plugin/plugin.json">

<violation number="1">
P2: The plugin manifest version was decremented to 1.2.0; this should remain/increment to 1.2.1 for a patch release.</violation>
</file>

<file name="plugins/mastra/.claude-plugin/plugin.json">

<violation number="1">
P2: The manifest version was downgraded to `1.3.0`; this should be `1.3.1` for the current release changes.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}