Skip to content

fix: standardize command frontmatter across plugin commands#107

Merged
sjnims merged 1 commit intomainfrom
fix/105-command-frontmatter-inconsistencies
Dec 11, 2025
Merged

fix: standardize command frontmatter across plugin commands#107
sjnims merged 1 commit intomainfrom
fix/105-command-frontmatter-inconsistencies

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 11, 2025

Summary

Standardize frontmatter formatting across both plugin commands to follow documented best practices from the command-development skill and official Claude Code documentation.

Problem

Fixes #105

The two plugin commands (create-plugin.md and create-marketplace.md) had inconsistent frontmatter that deviated from best practices:

  • Unnecessary quotes in argument-hint
  • Description exceeding 60 character recommendation
  • argument-hint not using bracket placeholder notation
  • JSON array format instead of comma-separated for allowed-tools
  • Missing Edit tool in create-marketplace.md

Solution

Applied consistent formatting following the command-development skill examples:

  • Use bracket notation [placeholder] for argument-hint without quotes
  • Keep descriptions concise (under 60 characters)
  • Use comma-separated format for allowed-tools (not JSON array)
  • Ensure both commands have consistent tool access

Alternatives Considered

Could have kept JSON array format for allowed-tools since both are technically valid, but comma-separated matches the skill documentation examples and is more readable.

Changes

  • plugins/plugin-dev/commands/create-plugin.md:

    • Remove quotes from argument-hint
    • Convert allowed-tools from JSON array to comma-separated

  • plugins/plugin-dev/commands/create-marketplace.md:

    • Shorten description from 86 to 47 characters
    • Use bracket notation for argument-hint
    • Add Edit tool for consistency with create-plugin.md
    • Convert allowed-tools from JSON array to comma-separated

Testing

  • Markdownlint passes on both files
  • Frontmatter syntax valid

🤖 Generated with Claude Code

@sjnims sjnims mentioned this pull request Dec 11, 2025
Closed
@sjnims sjnims self-assigned this Dec 11, 2025
@sjnims @claude
fix: standardize command frontmatter across plugin commands
c21b864 
Align both plugin commands with documented best practices from
the command-development skill and official Claude Code docs:

- create-plugin.md: Remove unnecessary quotes from argument-hint
- create-plugin.md: Use comma-separated allowed-tools format
- create-marketplace.md: Shorten description to under 60 chars
- create-marketplace.md: Use bracket notation for argument-hint
- create-marketplace.md: Add Edit tool for consistency
- create-marketplace.md: Use comma-separated allowed-tools format

Fixes #105

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@sjnims sjnims force-pushed the fix/105-command-frontmatter-inconsistencies branch from 5e02113 to c21b864 Compare December 11, 2025 01:19
@claude
Copy link
Copy Markdown

claude Bot commented Dec 11, 2025 •
edited
Loading

Claude finished @sjnims's task in 1m 17s —— View job

PR Review: Standardize Command Frontmatter

Summary: ✅ Looks great! This PR successfully standardizes the frontmatter across both plugin commands following documented best practices.

What's Good

  1. Consistent formatting applied: Both commands now use the same frontmatter style, which improves maintainability
  2. Follows documentation: Changes align perfectly with the command-development skill examples and frontmatter reference
  3. Improved readability: Comma-separated allowed-tools format is cleaner than JSON array
  4. Better argument hints: Bracket notation [marketplace-description] is more conventional and user-friendly
  5. Concise descriptions: The create-marketplace.md description was shortened from 86 to 47 characters, meeting the recommended 60-character guideline
  6. Added missing tool: Edit tool was appropriately added to create-marketplace.md for consistency with create-plugin.md
  7. Clean commit: Small, focused change that does exactly what it says

Markdown Linting

✅ Both files pass markdownlint with no errors.

Frontmatter Verification

I verified the changes against the command-development skill documentation and frontmatter reference:

create-plugin.md (plugins/plugin-dev/commands/create-plugin.md:1-4)

  • ✅ description: Clear and under 60 characters
  • ✅ argument-hint: Uses bracket notation without quotes
  • ✅ allowed-tools: Comma-separated format matches examples

create-marketplace.md (plugins/plugin-dev/commands/create-marketplace.md:1-4)

  • ✅ description: Shortened to 47 characters (was 86)
  • ✅ argument-hint: Changed to bracket notation [marketplace-description] (was "Optional marketplace description")
  • ✅ allowed-tools: Comma-separated format + added Edit tool for consistency

Changes Summary

File Change Reason
create-plugin.md Removed quotes from argument-hint Follows bracket notation convention
create-plugin.md Comma-separated allowed-tools Matches documentation examples
create-marketplace.md Shortened description Meets 60-char recommendation
create-marketplace.md Bracket notation for argument-hint Consistency with best practices
create-marketplace.md Added Edit tool Consistency with create-plugin.md
create-marketplace.md Comma-separated allowed-tools Matches documentation examples

Architecture Note

According to the frontmatter reference (plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md:76-86), both comma-separated and YAML array formats are technically valid for allowed-tools. The choice to use comma-separated is well-justified as it:

  • Matches the skill documentation examples
  • Is more concise and readable
  • Is consistent with how tools are typically listed in Claude Code

Checklist Verification

  • ✅ YAML frontmatter is valid
  • ✅ Descriptions are clear and concise (under 60 characters)
  • ✅ argument-hint uses proper bracket notation
  • ✅ allowed-tools format is consistent across both files
  • ✅ Both commands have equivalent tool access (both include Edit)
  • ✅ Markdownlint passes
  • ✅ Changes follow command-development skill best practices

Recommendation: Approve and merge. This is a clean improvement that standardizes the codebase according to documented best practices.

@claude claude Bot added refactor Code restructuring without behavior change component:command Commands layer effort:small < 1 hour labels Dec 11, 2025
@sjnims
Copy link
Copy Markdown
Owner Author

sjnims commented Dec 11, 2025

Rebased on main to resolve conflicts with #104.

PR #104 had already converted create-plugin.md's allowed-tools to comma-separated format and added Bash(git init:*). After rebasing, this PR now:

  • create-plugin.md: Only fixes the argument-hint (removes unnecessary quotes)
  • create-marketplace.md: All original fixes still apply (shorter description, bracket notation for argument-hint, add Edit tool, comma-separated allowed-tools)

@sjnims sjnims merged commit f32a1b0 into main Dec 11, 2025
7 checks passed
@sjnims sjnims deleted the fix/105-command-frontmatter-inconsistencies branch December 11, 2025 01:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@sjnims sjnims

Labels

component:command Commands layer effort:small < 1 hour refactor Code restructuring without behavior change

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: Command frontmatter inconsistencies with best practices

1 participant

@sjnims