Skip to content

docs(plugin-structure): remove extraneous README.md from skill#87

Merged
sjnims merged 1 commit intomainfrom
docs/84-remove-readme-from-plugin-structure
Dec 10, 2025
Merged

docs(plugin-structure): remove extraneous README.md from skill#87
sjnims merged 1 commit intomainfrom
docs/84-remove-readme-from-plugin-structure

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 10, 2025

Summary

Remove non-conformant README.md from the plugin-structure skill directory.

Problem

Fixes #84

The plugins/plugin-dev/skills/plugin-structure/README.md file doesn't conform to official Claude Code skill structure. Per the skills documentation, skill directories should only contain:

  • SKILL.md (required)
  • references/ (optional)
  • examples/ (optional)
  • scripts/ (optional)
  • assets/ (optional)

Solution

Delete the extraneous README.md file. All relevant information is already available in SKILL.md.

Alternatives Considered

  • Keep and rename to something valid: Rejected - the content is redundant with SKILL.md
  • Move to assets/: Rejected - not an asset, and still non-conformant metadata

Changes

  • Removed plugins/plugin-dev/skills/plugin-structure/README.md (108 lines)

Testing

  • Verified skill directory structure matches official spec
  • Linting passes (markdownlint)

🤖 Generated with Claude Code

Remove README.md that doesn't conform to official Claude Code skill
structure. Per skills.md documentation, skill directories should only
contain SKILL.md, references/, examples/, scripts/, and assets/.

The removed file contained redundant information already in SKILL.md
and word counts that could drift from actual values.

Fixes #84

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

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Copy link
Copy Markdown

claude Bot commented Dec 10, 2025

Claude finished @sjnims's task —— View job


PR Review Complete

Reviewing PR #87: Remove non-conformant README.md from plugin-structure skill

Summary

Looks good - This is a straightforward documentation cleanup that correctly removes a non-conformant file.


What's Good

  1. Correct Application of Spec: The deletion is appropriate. Per official Claude Code skills documentation, skill directories should only contain:

    • SKILL.md (required)
    • references/ (optional)
    • examples/ (optional)
    • scripts/ (optional)
    • assets/ (optional)

    The README.md file doesn't fit this structure.

  2. No Information Loss: After reviewing SKILL.md, all essential information is already present:

    • Comprehensive overview of plugin structure (520 lines)
    • Proper YAML frontmatter with name and description
    • Clear trigger phrases in description
    • References to detailed documentation in references/
    • References to working examples in examples/
  3. Clean Directory Structure: Post-deletion structure is compliant:

    plugin-structure/
    ├── SKILL.md
    ├── references/
    │   ├── component-patterns.md
    │   └── manifest-reference.md
    └── examples/
        ├── advanced-plugin.md
        ├── minimal-plugin.md
        └── standard-plugin.md
    
  4. Good Commit Message: Follows conventional commits format, includes fix reference, explains rationale.


Checklist Verification

  • Fixes the reported issue ([Docs]: Remove extraneous README.md from plugin-structure skill #84)
  • Skill directory structure matches official spec
  • SKILL.md contains all necessary information (name, description, comprehensive content)
  • Progressive disclosure pattern maintained (references/ and examples/ intact)
  • No markdown linting issues (file was deleted, no new/modified .md files)

Recommendation

Approve and merge. This PR correctly removes a non-conformant file while preserving all valuable information in the proper location (SKILL.md).

@claude claude Bot added documentation Improvements or additions to documentation component:skill Skills layer effort:small < 1 hour labels Dec 10, 2025
@sjnims sjnims merged commit e84cc83 into main Dec 10, 2025
9 of 10 checks passed
@sjnims sjnims deleted the docs/84-remove-readme-from-plugin-structure branch December 10, 2025 00:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:skill Skills layer documentation Improvements or additions to documentation effort:small < 1 hour

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Docs]: Remove extraneous README.md from plugin-structure skill

1 participant