Repository navigation
commands.md vs skill.md -- community guidelines #5
Description
For the community to effectively contribute custom plugins, it seems like more clarity is needed on the topic of creating the skill.md and the command.md. The Readme defines commands.md as specifically defining the slash commands / explicit actions that get triggered. Whereas skill.md is defined as the domain expertise, best practices, and step-by-step workflows. OK that makes sense; however, looking at the commands.md files, there is a lot more content than just defining the commands and actions. In fact in most examples I've reviewed, there's a lot of overlap. A good example is Legal/skills/contract-review and Legal/commands/review-contract
Additionally, it is unclear how skills get read based on command, and whether the available skills for any command are limited to those that are in the same plugin folder. There are no explicit references to skills in any command file or accompanying plugin json file. I had an entire conversation with Claude about this to try and figure it out and we concluded that it must be reading all skills for any command triggered by the user (but probably only the skills in that same plugin). Can someone clarify this?
Activity
dbz-max commentedon Feb 2, 2026
And I'd like to better understand how to migrate all the Claude AI skills into the new plugin world. Cowork can see those skills already.
docs: add architecture documentation for commands vs skills
Ashutosh0x commentedon Feb 8, 2026
Hi @ajd-beep,
This is a great point. Standardizing on a single file convention (like
skill.mdorcommands.md) would definitely make it easier for the community to contribute and for users to understand how to use different plugins.I'd be happy to help with this! If we can decide on a preferred convention (e.g., following the pattern in the core plugins), I can:
README.mdor a newCONTRIBUTING.mdwith these guidelines.Do you have a preference or any existing documentation I should look at for reference?
mohitgauniyal commentedon Feb 11, 2026
Hey, buddy. My PR #22 adds CONTRIBUTING.md which includes guidelines for both. Would this address your concern? Happy to add more specific examples if needed!
Add state-machine schemas (leads/contracts/engagements.db)
Multi-tenant: tenant_state_dir() helper + footgun documentation