Add contextual skills for development workflows #2454
Conversation
This implements a comprehensive skill system to provide context-aware documentation for development workflows: - activitypub-dev-cycle: Environment setup, testing, linting, and builds - activitypub-php-conventions: WordPress coding standards and patterns - activitypub-pr-workflow: PR creation and review processes - activitypub-federation: ActivityPub protocol specification - activitypub-testing: PHPUnit and Playwright test patterns - activitypub-release: Version management and releases - activitypub-integrations: Third-party plugin integration Skills use cross-references to reduce duplication while maintaining context-appropriate information. Federation skill focuses on protocol understanding rather than implementation details. Updates .gitignore to track shared skills while ignoring local overrides using the *.local.* pattern.
|
@pfefferle This will need some more work and polish, there's also still a lot of overlap. I'm curious if this would be helpful to make Claude work better for us. Curious for your feedback/thoughts. See |
|
I’m not entirely convinced yet. I like the idea of improving how we use AI, but I’d prefer a more generic approach. We’re both using Claude right now, but that could change, and I don’t think we should have to rebuild this whole structure every time we switch models. On top of that, the examples, class structure, and coding standards files feel like they duplicate what already exists in the codebase. The examples and structure are already reflected in the code, and our coding standards are defined in |
|
I think a lot of these files provide generally helpful information. Let's see how we can place them in the folders of the features they describe and simply point claude to these? (see my comment to the integrations file) Maybe we can also re-use our docs folder or move some of these there? |
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a comprehensive skill system for the WordPress ActivityPub plugin to provide context-aware documentation for AI coding assistants. The skills cover development workflows, coding standards, PR processes, federation protocol, testing patterns, release management, and third-party integrations.
Key Changes:
- Added 7 skill files covering different aspects of development (dev-cycle, PHP conventions, PR workflow, federation, testing, release, integrations)
- Created CLAUDE.md documentation explaining the skill system and local override mechanism
- Updated .gitignore to track skills while ignoring local overrides (
.claude/**/*.local*) - Added settings.json to configure allowed skills
Reviewed Changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| CLAUDE.md | Provides overview of the skill system and instructions for AI assistants on using skills and local overrides |
| .gitignore | Modified to track .claude skills directory while ignoring local override files |
| .claude/settings.json | Configures the list of allowed skills for the project |
| .claude/skills/activitypub-testing/SKILL.md | Documents PHPUnit and Playwright testing patterns with cross-references to tests/README.md |
| .claude/skills/activitypub-release/SKILL.md | Covers version management, changelog workflow, and release processes using Jetpack Changelogger |
| .claude/skills/activitypub-pr-workflow/SKILL.md | Details branch naming conventions, PR requirements, and code review workflows |
| .claude/skills/activitypub-php-conventions/SKILL.md | Defines PHP coding standards, WordPress patterns, and architectural conventions with phpcs.xml reference issues |
| .claude/skills/activitypub-integrations/SKILL.md | Documents third-party plugin integration patterns with inaccurate examples for non-existent integrations |
| .claude/skills/activitypub-federation/SKILL.md | Explains ActivityPub protocol specification and federation concepts with proper references to FEDERATION.md |
| .claude/skills/activitypub-dev-cycle/SKILL.md | Covers wp-env setup, testing commands, linting, and build processes with port number inconsistencies |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Adds BuddyPress activity support | ||
| - Custom member transformers | ||
| - Group activity federation | ||
|
|
||
| ### WooCommerce | ||
| - Product post type support | ||
| - Order activity notifications | ||
| - Customer review federation | ||
|
|
||
| ### bbPress | ||
| - Forum topic federation | ||
| - Reply activities | ||
| - User forum profiles | ||
|
|
There was a problem hiding this comment.
The "Existing Integrations" section describes integrations for BuddyPress, WooCommerce, and bbPress. However, WooCommerce and bbPress integrations don't exist in the codebase.
While BuddyPress integration exists (integration/class-buddypress.php), it doesn't include the features described here (custom member transformers, group activity federation). The actual BuddyPress integration only adds user metadata to author arrays.
Suggested fix: Remove the WooCommerce and bbPress sections, and update the BuddyPress description to accurately reflect what it does (adds BuddyPress user metadata and profile URLs).
| - Adds BuddyPress activity support | |
| - Custom member transformers | |
| - Group activity federation | |
| ### WooCommerce | |
| - Product post type support | |
| - Order activity notifications | |
| - Customer review federation | |
| ### bbPress | |
| - Forum topic federation | |
| - Reply activities | |
| - User forum profiles | |
| - Adds BuddyPress user metadata and profile URLs to author arrays |
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>
Reduced skill content from 1,730 to 1,100 lines by removing generic content that duplicates existing documentation. Skills now focus on: - Plugin-specific conventions and patterns - Quick reference commands and cheat sheets - Workflow guidance and critical reminders - Links to comprehensive documentation Changes: - activitypub-php-conventions: 422 → 212 lines (focus on plugin architecture) - activitypub-dev-cycle: 239 → 140 lines (focus on workflows) - activitypub-pr-workflow: 328 → 240 lines (keep critical warnings) - activitypub-release: 151 → 122 lines (focus on quick reference) - activitypub-federation: Added FEDERATION.md references - docs/development-environment.md: Added pre-commit hook note
|
I gave this another iteration and removed about 30% of the volume in favor of references to existing docs, etc. @pfefferle Let me know what you think? |
obenland
added
the
Skip Changelog
Added .claude and CLAUDE.md to the .distignore file to prevent these files from being included in distribution builds.
Proposed changes:
This PR implements a comprehensive skill system to provide context-aware documentation for development workflows:
Skills use cross-references to reduce duplication while maintaining context-appropriate information. Federation skill focuses on protocol understanding rather than implementation details.
Other information:
Testing instructions:
.claude/skills/directory structure.gitignoreproperly tracks skills while ignoring*.local.*filesCLAUDE.mdfor documentation on the skills system