feat: create Claude Code plugin for sharing commands across repos

[atxtechbro]

Git Statistics

.claude-plugin/commands/close-issue.md        |  1 +
.claude-plugin/commands/create-issue.md       |  1 +
.claude-plugin/commands/extract-best-frame.md |  1 +
.claude-plugin/commands/retro.md              |  1 +
.claude-plugin/marketplace.json               | 13 +++++++++++++
.claude-plugin/plugin.json                    |  8 ++++++++
6 files changed, 25 insertions(+)

Summary

Transforms dotfiles into a Claude Code plugin that can be installed in any repo, solving the problem of sharing slash commands across multiple repositories.

The Problem: PR #1344 added /close-issue via symlink in dotfiles, but other repos (like lifehacking) can't access it. The old command generation system that synced to ~/.claude/commands/ was removed in #1320 for provider-agnostic reasons.

The Solution: Use Claude Code's official plugin system introduced in their recent plugins announcement. Dotfiles becomes a shareable plugin that other repos can install.

What Changed

Created plugin structure:

.claude-plugin/
├── plugin.json              # Plugin metadata
├── marketplace.json         # Distribution manifest  
└── commands/                # Symlinked to knowledge base
    ├── close-issue.md      → ../../knowledge/procedures/close-issue-procedure.md
    ├── create-issue.md     → ../../knowledge/procedures/issue-creation-procedure.md
    ├── extract-best-frame.md → ../../knowledge/procedures/extract-best-frame-procedure.md
    └── retro.md           → ../../knowledge/procedures/retro-procedure.md

Benefits

🎯 Modern Approach:

• Official Claude Code extension system (vs custom generation scripts)
• Commands shareable across all repos via plugin install
• Per-repo control (install only where needed)

🔧 Technical:

• Single source of truth (knowledge base remains authoritative)
• Symlinks ensure zero duplication
• Expandable with agents, hooks, MCP servers later
• Works with both local paths and GitHub distribution

Installation in Other Repos

Local (for testing):

/plugin marketplace add ~/ppv/pillars/dotfiles
/plugin install dotfiles-commands

GitHub (after merge):

/plugin marketplace add atxtechbro/dotfiles
/plugin install dotfiles-commands@atxtechbro

Implementation Notes

This "dotfiles-as-plugin" approach:

• Leverages official Claude Code plugin system vs maintaining custom sync scripts
• Enables sharing of dotfiles setup with other users
• Follows systems-stewardship principle (single source of truth in knowledge base)
• Can be expanded to include custom agents and hooks in the future

Test Plan

• Create .claude-plugin/ structure with manifests
• Symlink commands to knowledge base procedures
• Test local installation in lifehacking repo
• Verify /close-issue autocomplete works after plugin install
• Test GitHub-based installation after merge

---

Related: Continues the work from #1344 (symlink approach) by making it shareable across repos

[amazon-q-developer]

⏳ Code review in progress. Analyzing for code quality issues and best practices. Detailed findings will be posted upon completion.

Using Amazon Q Developer for GitHub

Amazon Q Developer¹ is an AI-powered assistant that integrates directly into your GitHub workflow, enhancing your development process with intelligent features for code development, review, and transformation.

Slash Commands

Command	Description
/q <message>	Chat with the agent to ask questions or request revisions
/q review	Requests an Amazon Q powered code review
/q help	Displays usage information

Features

Agentic Chat
Enables interactive conversation with Amazon Q to ask questions about the pull request or request specific revisions. Use /q <message> in comment threads or the review body to engage with the agent directly.

Code Review
Analyzes pull requests for code quality, potential issues, and security concerns. Provides feedback and suggested fixes. Automatically triggered on new or reopened PRs (can be disabled for AWS registered installations), or manually with /q review slash command in a comment.

Customization

You can create project-specific rules for Amazon Q Developer to follow:

1. Create a .amazonq/rules folder in your project root.
2. Add Markdown files in this folder to define rules (e.g., cdk-rules.md).
3. Write detailed prompts in these files, such as coding standards or best practices.
4. Amazon Q Developer will automatically use these rules when generating code or providing assistance.

Example rule:

All Amazon S3 buckets must have encryption enabled, enforce SSL, and block public access.
All Amazon DynamoDB Streams tables must have encryption enabled.
All Amazon SNS topics must have encryption enabled and enforce SSL.
All Amazon SNS queues must enforce SSL.

Feedback

To provide feedback on Amazon Q Developer, create an issue in the Amazon Q Developer public repository.

For more detailed information, visit the Amazon Q for GitHub documentation.

Footnotes

1. Amazon Q Developer uses generative AI. You may need to verify generated code before using it in your environment. See the AWS Responsible AI Policy. ↩

[amazon-q-developer]

Overall Assessment

This PR introduces an innovative approach to sharing Claude Code commands across repositories using the official plugin system. The concept is solid and addresses a real need for command portability, but there are several implementation issues that need to be addressed before this will function correctly.

Critical Issues

Symlink Implementation: The most critical issue is that the command files contain path strings rather than actual symbolic links. Claude Code will read the file content (the path string) instead of following symlinks to the target procedures. This needs to be fixed for the plugin to work.

Plugin Metadata: The plugin.json is missing essential fields like command definitions, entry points, and engine compatibility requirements that Claude Code plugins typically need.

Recommendations

1. Fix symlinks: Use actual ln -s commands to create proper symbolic links instead of files containing path strings
2. Enhance plugin.json: Add command definitions, main entry point, and engine compatibility fields
3. Add version tracking: Include version information in marketplace.json for better release management
4. Fix file formatting: Ensure all files have proper trailing newlines

Strengths

• Excellent architectural approach using official Claude Code plugin system
• Clear documentation and rationale in the PR description
• Good separation of concerns with knowledge base as single source of truth
• Well-thought-out installation instructions for both local and GitHub scenarios

The core idea is excellent and will provide significant value once the implementation details are corrected.

[amazon-q-developer]

The symlink files contain only relative paths as text content rather than actual symbolic links. This approach won't work as intended because Claude Code will read the file content (the path string) instead of following a symlink to the target file. Consider using actual symbolic links or copying the content directly.

[amazon-q-developer]

The plugin.json is missing several important fields that are typically required for Claude Code plugins. Consider adding fields like main (entry point), commands (command definitions), and engines (compatibility requirements) to ensure proper plugin functionality.

[amazon-q-developer]

The marketplace.json structure looks correct, but consider adding version information and more detailed metadata. The source field pointing to "." is appropriate for a self-contained plugin, but you may want to add a version field to track plugin releases.

Suggested change

	{
	"name": "dotfiles-commands",
	{
	"name": "dotfiles-commands",
	"source": ".",
	"version": "1.0.0",
	"description": "Shared procedures and slash commands from dotfiles knowledge base",
	"keywords": ["commands", "procedures", "github", "automation"]
	}

[amazon-q-developer]

Same issue as with close-issue.md - this file contains a path string rather than being an actual symlink. All command files in the commands directory have this same problem and will not function as intended.

[amazon-q-developer]

🛑 Missing Newline: The file is missing a trailing newline character, which can cause issues with Git and text processing tools. This is indicated by the "No newline at end of file" message in the diff.

[amazon-q-developer]

Consider using a more descriptive name for the marketplace. "dotfiles-marketplace" might be confusing since this is specifically for command sharing. Something like "dotfiles-commands-marketplace" would be clearer about the purpose.