Add naming conventions and streamline skills documentation#29
Merged
Conversation
…and discoverability
… ensure alignment with best practices
- Removed aliases from various skills in the .claude/skills directory to streamline usage. - Updated descriptions for clarity and consistency across skills related to deployment, debugging, and testing. - Enhanced agent instructions in AGENTS.md files across multiple projects, emphasizing TDD practices and common mistakes. - Consolidated testing guidelines and project layouts for better organization and accessibility. - Deleted outdated AGENTS.md files from unit test projects and created a new consolidated AGENTS.md for tests.
There was a problem hiding this comment.
Pull request overview
This pull request implements a comprehensive naming convention system for Claude skills, transitioning from hyphenated names to a structured prefix__slug format. The changes enhance discoverability by grouping skills by technology domain (e.g., marten__, wolverine__, test__, frontend__) and eliminate aliases to reduce confusion.
Changes:
- Renamed all 28 skills from hyphenated format (e.g.,
scaffold-write) to prefixed format (e.g.,wolverine__create_operation) - Added comprehensive naming conventions documentation (
.claude/skills/NAMING-CONVENTIONS.md) - Updated all skill cross-references and AGENTS.md files across the repository
- Consolidated test AGENTS.md files (added
tests/AGENTS.md, removed redundant project-specific ones) - Removed
.github/copilot-instructions.md(content consolidated into root AGENTS.md) - Removed aliases from all documentation for clarity
Reviewed changes
Copilot reviewed 47 out of 67 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
.claude/skills/NAMING-CONVENTIONS.md |
New comprehensive naming guide with prefix taxonomy and quality gates |
.claude/skills/README.md |
Updated skill catalog to reflect new naming (28 skills) |
.claude/skills/*/SKILL.md |
All 28 skill files renamed and frontmatter updated to match new convention |
AGENTS.md |
Root file updated with new skill names, aliases removed |
tests/AGENTS.md |
New consolidated testing guidance |
tests/BookStore.AppHost.Tests/AGENTS.md |
Updated with new skill references |
tests/BookStore.ApiService.UnitTests/AGENTS.md |
Updated with new skill references |
src/*/AGENTS.md |
All source AGENTS.md files updated with new skill names |
docs/guides/agent-guide.md |
Updated with new skill catalog and workflow examples |
.claude/skills/*/templates/ |
New template files added for Wolverine operations and Marten projections |
Comments suppressed due to low confidence (7)
.claude/skills/test__integration_scaffold/SKILL.md:299
- The markdown link text still uses the old skill name
run-unit-testsinstead oftest__unit_suite. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
.claude/skills/test__integration_scaffold/SKILL.md:346 - The markdown link text still uses the old skill name
verify-featureinstead oftest__verify_feature. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
.claude/skills/test__integration_suite/SKILL.md:35 - The markdown link text still uses the old skill name
scaffold-testinstead oftest__integration_scaffold. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
.claude/skills/meta__write_agents_md/templates/CHECKLIST.md:28 - Line 28 mentions documenting "Skill aliases" (e.g.,
/sco→wolverine__create_operation), but the PR description states that aliases were removed for clarity. This checklist item should either be removed or clarified to indicate that aliases are no longer recommended.
.claude/skills/test__integration_scaffold/SKILL.md:347 - The markdown link text still uses the old skill name
run-integration-testsinstead oftest__integration_suite. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
.claude/skills/test__integration_scaffold/SKILL.md:348 - The markdown link text still uses the old skill name
run-unit-testsinstead oftest__unit_suite. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
.claude/skills/test__integration_scaffold/SKILL.md:298 - The markdown link text still uses the old skill name
run-integration-testsinstead oftest__integration_suite. While the link target is correct, the display text should match the actual skill name for consistency and clarity.
docs/guides/agent-guide.md
Outdated
|
|
||
| ### Skill Cross-Referencing System | ||
|
|
||
| All 17 skills include "Related Skills" sections that reference each other, creating an interconnected ecosystem: |
There was a problem hiding this comment.
The text states "All 17 skills include 'Related Skills' sections" but the catalog now contains 28 skills, not 17. This count should be updated to reflect the current number of skills.
Owner
Author
|
@copilot open a new pull request to apply changes based on the comments in this thread |
Contributor
Co-authored-by: aalmada <534533+aalmada@users.noreply.github.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Enhance consistency and discoverability of Claude skills by implementing new naming conventions. Update documentation to align with best practices and remove aliases for clarity. Refactor AGENTS.md files to improve guidance on agent skills creation.