Skip to content

Introduce a skeleton directory for hosting Claude plugins #6656

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jrhee17 wants to merge 4 commits into
base: main
Choose a base branch
from
+53 −0
Open

Introduce a skeleton directory for hosting Claude plugins #6656

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e2dae1a
minimal impl
jrhee17 Mar 5, 2026
ab420dd
generalize the description
jrhee17 Mar 6, 2026
c8ab575
address comment by @ikhoon
jrhee17 Mar 16, 2026
6492637
Apply suggestion from @jrhee17
jrhee17 Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"name": "armeria",
"owner": {
"name": "armerian",
"email": "dl_armeria@linecorp.com"
},
"metadata": {
"description": "Claude plugin for the Armeria microservice framework, providing AI-assisted guidance for common development tasks",
"version": "0.0.1"
},
"plugins": [
{
"name": "armeria",
"source": {
"source": "git-subdir",
Copy link
Contributor

@ikhoon ikhoon Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noted Claude partially clones to fetch the sub directory.
https://code.claude.com/docs/en/plugin-marketplaces#git-subdirectories

"url": "https://github.com/line/armeria.git",
"path": "tools/claude-plugins/armeria"
}
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Check if plugin manifest exists
if [ -f tools/claude-plugins/armeria/.claude-plugin/plugin.json ]; then
  echo "✓ Plugin manifest found"
  cat tools/claude-plugins/armeria/.claude-plugin/plugin.json
else
  echo "✗ Plugin manifest NOT found"
fi

echo
echo "=== Directory structure under tools/claude-plugins/armeria ==="
fd -HI . tools/claude-plugins/armeria -t f 2>/dev/null | head -30

echo
echo "=== Checking for component directories ==="
for dir in skills commands tools integrations; do
  if [ -d "tools/claude-plugins/armeria/$dir" ]; then
    echo "✓ Found /$dir"
    fd -HI . tools/claude-plugins/armeria/$dir -t f 2>/dev/null
  fi
done

Repository: line/armeria

Length of output: 297

The referenced plugin directory lacks required manifest and components for marketplace installation.

This marketplace entry cannot function: tools/claude-plugins/armeria/ is missing the required .claude-plugin/plugin.json manifest and contains only empty placeholder directories. The skills/ directory exists but has no actual components (only .gitkeep). Create the plugin manifest and add at least one skill or command before users can install this plugin via the marketplace.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.claude-plugin/marketplace.json around lines 13 - 18, The marketplace entry
for "armeria" points to a plugin directory that only contains placeholders;
create a proper .claude-plugin/plugin.json manifest in the armeria plugin
(include required fields like name, version, description, author,
entrypoint/handler, and any permissions) and add at least one real component
under the skills/ directory (replace the .gitkeep with a skill folder that
includes its own skill manifest and implementation/command files), then ensure
the new skill's entrypoint matches the plugin manifest so the marketplace can
install and load the plugin.

}
]
}
1 change: 1 addition & 0 deletions site-new/sidebarsCommunity.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const sidebars: SidebarsConfig = {
'developer-guide',
'code-of-conduct',
'design-resources',
'claude-plugin',
],
};

Expand Down
24 changes: 24 additions & 0 deletions site-new/src/content/community/claude-plugin.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Claude Plugin

We maintain a [Claude](https://claude.ai/) plugin that may be useful for the community to use AI-powered guidance for development.

## Installation

You can install the Armeria Claude plugin from the marketplace:

```bash
/plugin marketplace add line/armeria
/plugin install armeria@armeria
Copy link
Contributor

@ikhoon ikhoon Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: armeria@armeria looks repetitive. Should we use a different plugin name like assistant@armeria or helper@armeria?

```

## Contributing

To contribute new features to the Claude plugin:

1. Create or update a markdown file in `<project dir>/tools/claude-plugins/armeria`
2. Reference official Armeria documentation URLs if applicable
3. Submit a pull request for review
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

find site-new -type f -name "claude-plugin.mdx" | head -5

Repository: line/armeria

Length of output: 104

🏁 Script executed:

# Once we locate the file, read the specific lines
sed -n '1,30p' site-new/src/content/community/claude-plugin.mdx 2>/dev/null | cat -n

Repository: line/armeria

Length of output: 902

🏁 Script executed:

# Check if tools/claude-plugins/armeria directory exists and what structure it has
find tools/claude-plugins/armeria -type f -o -type d 2>/dev/null | sort

Repository: line/armeria

Length of output: 165

🌐 Web query:

Claude Code plugin skills commands directory structure reference docs

💡 Result:

Official reference docs for Claude Code plugins / skills / commands (including directory layout):

  • Plugins reference (schema + directory structure + troubleshooting): “Plugins reference” (docs.claude.com)
  • Create plugins (tutorial + manifest + testing): “Create plugins” (docs.claude.com)
  • Skills authoring guide (SKILL.md format, supporting files, env vars): “Extend Claude with skills” (docs.claude.com)

Canonical plugin directory structure (skills + commands)

A plugin is a normal folder; only the manifest lives under .claude-plugin/. Everything else (skills/commands/etc.) must be at the plugin root. (docs.claude.com)

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       ├── SKILL.md
│       ├── reference.md        (optional)
│       └── scripts/            (optional)
├── commands/                   (legacy; markdown files)
│   └── something.md
├── agents/
├── hooks/
│   └── hooks.json
├── settings.json               (optional)
├── .mcp.json                   (optional)
└── .lsp.json                   (optional)

(docs.claude.com)

Key “skills vs commands” structure rules

  • Skills: skills/<skill-name>/SKILL.md (a directory per skill). Supporting files (reference docs, examples, scripts) live alongside SKILL.md inside that skill directory. (docs.claude.com)
  • Commands: in plugins, commands/ is treated as legacy skill markdown files; new work should prefer skills/. (docs.claude.com)
  • Useful paths:
    • ${CLAUDE_PLUGIN_ROOT} → absolute path to the plugin root (useful for scripts/hooks). (docs.claude.com)
    • ${CLAUDE_SKILL_DIR} → directory containing the active skill’s SKILL.md (useful for skill-local scripts/files). (docs.claude.com)

Citations:

Point contributors at skills/ or commands/, not the plugin root.

Line 18 currently tells people to add markdown directly under tools/claude-plugins/armeria, but Claude Code only discovers plugin functionality from skills/<skill-name>/SKILL.md or commands/<command-name>.md at the plugin root. As written, contributors can follow these steps and still add files that Claude Code never loads.

✏️ Proposed doc fix 
-1. Create or update a markdown file in `<project dir>/tools/claude-plugins/armeria`
+1. Create or update a plugin component under `<project dir>/tools/claude-plugins/armeria`, for example:
+   - `skills/<skill-name>/SKILL.md` for a skill, or
+   - `commands/<command-name>.md` for a command
 2. Reference official Armeria documentation URLs if applicable
 3. Submit a pull request for review
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
1. Create or update a markdown file in `<project dir>/tools/claude-plugins/armeria`
2. Reference official Armeria documentation URLs if applicable
3. Submit a pull request for review
1. Create or update a plugin component under `<project dir>/tools/claude-plugins/armeria`, for example:
- `skills/<skill-name>/SKILL.md` for a skill, or
- `commands/<command-name>.md` for a command
2. Reference official Armeria documentation URLs if applicable
3. Submit a pull request for review
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@site-new/src/content/community/claude-plugin.mdx` around lines 18 - 20,
Update the step that instructs contributors to add documentation under
tools/claude-plugins/armeria so it points to the discovered locations: instruct
them to create or update files under
tools/claude-plugins/armeria/skills/<skill-name>/SKILL.md or
tools/claude-plugins/armeria/commands/<command-name>.md (not the plugin root),
and note that Claude Code only loads SKILL.md in skills/ and .md files in
commands/ so content placed elsewhere will be ignored.


## References

- [Claude Plugin Marketplaces Documentation](https://code.claude.com/docs/en/plugin-marketplaces)
4 changes: 4 additions & 0 deletions site-new/src/content/community/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ Check out [the developer guide](/community/developer-guide) to learn how to buil

We expect contributors to follow [our code of conduct](/community/code-of-conduct).

## Using AI assistants? 🤖

We provide a [Claude plugin](/community/claude-plugin) to help you work with Armeria more effectively using AI-powered assistance.

## Hall of fame 🏛️

<ThankYou
Expand Down
Empty file added tools/claude-plugins/armeria/skills/.gitkeep
View file
Open in desktop
Empty file.
Loading