[Feature]: Meta-Skill

[kylesnowschwartz]

Problem or Need

Hello, thanks again for maintaining this. I'm curious if you've thought about adding a 'meta-skill' to help guide a user when they're unsure.

Proposed Solution

I've added one in my fork which has been working nicely: https://github.com/kylesnowschwartz/plugin-dev/blob/main/plugins/plugin-dev/skills/plugin-dev-guide/SKILL.md

Which component would this affect?

Command (/plugin-dev:*)

Specific Component (if applicable)

No response

Alternatives Considered

No response

Additional Context

Unrelated - I'm curious how you plan to keep the skills up to date with Anthropic's pace of change. For example, recent work has combined commands/skills and made them effectively the same tool in Claude-Code. Additionally, new tools like 'hooks' in yaml frontmatter and 'fork' strategies have been added to skills/agents. I'm not sure if Anthropic has updated their docs yet (I doubt it) - do you plan try and keep up with updates like these and make manual edits to the skills?

Thanks! I'd be happy to help out if you'd like contributions.

How important is this feature to you?

Low - Just a suggestion

Contribution

• I'm willing to help implement this feature

[github-actions]

👋 Thanks for opening your first issue! We appreciate your contribution to plugin-dev.

Please make sure you've provided all the requested information in the issue template. Our maintainers will review this soon.

[sjnims]

@kylesnowschwartz hey! I will take a look at this probably over the coming weekend...I've been focusing on my plugin automated test framework: https://github.com/sjnims/cc-plugin-eval. It works but...it's slow as molasses, so I'm trying to figure that out.

Generally speaking, the tact I take for constantly evolving things like plugins I'm creating that are for a specific open source project, I like to to clone the repo locally and use it as a reference - I'll periodically pull down new updates, then fire up Claude Code and ask "Comprehensively familiarize yourself with this project. Since xyz date, what new features or breaking changes have occurred that we need to consider in our project?" In this case, we can't really do that because Claude Code is closed source AND we know that the official docs aren't exactly stellar. What I do in this scenario is poke and prod at the Agent SDK since it can load plugins AND the docs are better AND the repo is all there for you to feed into Claude for RAG. The last place I look is in the Claude Code CHANGELOG for any interesting updates left in there.

Long story short, there isn't a sure fire way to do it in this case, but with enough poking and prodding, you can sus it all out.

[sjnims]

@claude please provide expert commentary on if/how changes would need to be made to this project to accommodate the recent merging of skills and commands.

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[sjnims]

@kylesnowschwartz let's see what Claude comes up with 😄

[sjnims]

Let's try that again...

@claude please provide expert commentary on if/how changes would need to be made to this project to accommodate the recent merging of skills and commands.

[claude]

Claude finished @sjnims's task in 3m 52s —— View job

---

Analysis: Skills/Commands Merging Impact

Analyzing the impact of Claude Code's recent merging of skills and commands on this project.

Tasks

• Read current project structure and key files
• Analyze current skills vs commands architecture
• Assess impact of skills/commands merging
• Provide recommendations
• Comment on meta-skill proposal

---

Current Architecture Analysis

Skills in plugin-dev:

• Location: plugins/plugin-dev/skills/*/SKILL.md
• 8 skills total: hook-development, mcp-integration, plugin-structure, plugin-settings, command-development, agent-development, skill-development, marketplace-structure
• Purpose: Provide specialized knowledge/documentation loaded into context when triggered
• Triggering: Automatic based on description trigger phrases (e.g., "create a hook", "add MCP server")
• Structure: YAML frontmatter + markdown body + optional references/examples/scripts directories
• Progressive disclosure: Metadata always loaded, body when triggered, resources as needed
• Output: Inform Claude's responses with domain knowledge

Commands in plugin-dev:

• Location: plugins/plugin-dev/commands/*.md
• 3 commands total: start.md, create-plugin.md, create-marketplace.md
• Purpose: User-invokable workflows that execute specific tasks
• Triggering: Explicit user invocation (e.g., /plugin-dev:start)
• Structure: YAML frontmatter + markdown instructions TO Claude
• Output: Execute multi-phase workflows, create files, interact with user

Key Distinction (as of plugin-dev v0.2.1):

• Skills = Knowledge/documentation (passive, auto-triggered)
• Commands = Workflows/actions (active, user-invoked)

---

Impact Assessment: Skills/Commands Merging

What the Merging Means

Based on the user's description and current Claude Code trends, the "merging" appears to mean:

1. Unified file format: Skills and commands now share the same markdown + YAML frontmatter structure
2. Convergence of capabilities: The distinction between "knowledge" and "action" is blurring
3. Both can trigger automatically: Skills can now contain workflow instructions, not just knowledge
4. Both can be invoked manually: Commands with slash syntax remain, but skills can also contain actionable workflows

Critical Differences That Remain

Despite convergence, there are still fundamental distinctions:

Aspect	Skills	Commands
Invocation	Auto-triggered by description matching	Manual via /command-name
User visibility	Invisible to user (happens automatically)	Explicit user action
Directory structure	skills/skill-name/SKILL.md + resources	commands/command-name.md
Purpose	"When should Claude know this?"	"What can user ask Claude to do?"
Progressive disclosure	Built for it (references/, examples/, scripts/)	Flat structure

What Needs to Change in plugin-dev

Good news: Minimal breaking changes required. Here's why:

1. File formats already aligned: Both use markdown + YAML frontmatter
2. Frontmatter fields already compatible: description, allowed-tools, model work in both
3. The architecture is already sound: Skills teach knowledge, commands execute workflows

However, there are clarifications and enhancements needed:

---

Recommendations for plugin-dev

1. Documentation Updates (High Priority)

Update CLAUDE.md and README.md:

• Clarify that skills and commands share file format but serve different purposes
• Add note about the "merging" trend and how plugin-dev handles it
• Emphasize: "Skills auto-trigger to provide knowledge; commands are user-invoked workflows"

Update skill-development/SKILL.md:

• Add section on "Skills vs Commands in Modern Claude Code"
• Explain when to create a skill vs command
• Note that skills can now contain workflow instructions if appropriate

Update command-development/SKILL.md:

• Add section on "Commands vs Skills in Modern Claude Code"
• Clarify the invocation model difference
• Document that commands can reference skills for domain knowledge

2. New Frontmatter Fields Support (Medium Priority)

Based on the user's mention of new features, document/support:

hooks in YAML frontmatter:

If Claude Code now supports inline hook definitions in skills/commands, add:

• Documentation in hook-development skill
• Examples in command-development skill
• Update frontmatter reference docs

fork strategies:

If this is a new concurrency/execution model, add:

• Documentation explaining fork strategies
• Examples of when to use them
• Integration guidance

3. Meta-Skill Consideration (Addressed Below)

The proposed plugin-dev-guide meta-skill addresses a real need but should be evaluated carefully.

4. Testing and Validation (Medium Priority)

Update validation scripts:

• Ensure validators handle both old and new patterns
• Test that skills can contain workflow instructions
• Verify commands work with new frontmatter fields

Update component-validation.yml workflow:

• Add checks for new frontmatter fields
• Ensure CI validates both patterns

5. Examples and Templates (Low Priority)

Create hybrid examples:

• Show skill with workflow instructions (not just knowledge)
• Show command that leverages skill knowledge
• Demonstrate the "best of both worlds" approach

---

Commentary on Meta-Skill Proposal

The Need is Real

The user (@kylesnowschwartz) identified a genuine gap: new users don't know which skill/command to use. The current architecture assumes users will:

1. Read /help to see available skills/commands
2. Recognize which one matches their need
3. Invoke it correctly

This works for experienced users but not newcomers.

Evaluation of the Proposed Solution

Strengths of plugin-dev-guide meta-skill:

• Lower barrier to entry: Users can ask "how do I..." and get guided to the right resource
• Discovery mechanism: Acts as a router to other skills/commands
• Aligns with Claude Code's auto-triggering: Triggers on vague queries like "I want to create a plugin"

Potential concerns:

• Overlaps with /plugin-dev:start command: The start command already routes users to create-plugin or create-marketplace
• Noise in context: Meta-skills add overhead since skill metadata is always loaded
• Maintenance burden: Needs updating whenever skills/commands change
• May trigger too broadly: Could interfere with normal conversations

Alternative/Complementary Approaches

Option A: Enhance /plugin-dev:start command

Instead of a meta-skill, expand the start command to handle all entry points:

---
description: Start plugin development - guides to the right skill or workflow
argument-hint: [what you want to do]
---

Help user discover the right skill or command based on their needs:
- Creating plugins → /plugin-dev:create-plugin
- Creating marketplaces → /plugin-dev:create-marketplace
- Learning about hooks → Reference hook-development skill
- Learning about MCP → Reference mcp-integration skill
...

Pros: Single entry point, explicit invocation, less context noise
Cons: Requires user to know to run /plugin-dev:start

Option B: Hybrid - Add meta-skill + enhance start command

1. Keep /plugin-dev:start for users who know they want the plugin
2. Add plugin-dev-guide skill for ambient "I'm lost" triggering
3. Guide skill should be VERY targeted (only trigger on genuinely vague queries)

Pros: Best of both worlds - explicit + ambient support
Cons: More components to maintain

Option C: Enhance skill descriptions for better auto-triggering

Review all 8 skill descriptions and ensure they trigger on common user queries:

• hook-development: Add "automate tasks", "run code on events"
• command-development: Add "create shortcuts", "make workflows"
• etc.

Pros: No new component needed, improves existing architecture
Cons: May not help truly lost users

---

My Recommendation

Implement Option B (Hybrid Approach):

1. Add the plugin-dev-guide meta-skill with these constraints:

   • Very narrow triggering: Only on "how do I use plugin-dev", "what can plugin-dev do", "guide me", "I'm new to plugin-dev"
   • Lightweight content: Just a router/index, not duplicate knowledge
   • Clear separation: Guide to resources, don't try to teach them inline
   • Link to start command: "For step-by-step plugin creation, run /plugin-dev:start"

2. Enhance skill descriptions (Option C) to improve auto-triggering for specific tasks

3. Update documentation to clarify skills vs commands in the merged world

Proposed plugin-dev-guide Structure

---
name: plugin-dev-guide
description: This skill should be used when the user asks "how do I use plugin-dev", "what can plugin-dev do", "plugin-dev guide", "I'm new to plugin-dev", "getting started with plugin-dev", or needs orientation on available skills and commands without knowing which one to use.
allowed-tools: Skill, SlashCommand, TodoWrite, AskUserQuestion
---

# Plugin-Dev Guide

You're using the plugin-dev toolkit for creating Claude Code plugins. Here's how to get started:

## Quick Start

**For step-by-step plugin creation:**
Run `/plugin-dev:start` to launch the guided workflow.

## Available Skills (Auto-Trigger)

Ask about these topics, and the relevant skill will load automatically:

- **Hooks**: "create a hook", "automate on events" → hook-development skill
- **MCP**: "add MCP server", "integrate API" → mcp-integration skill
- **Plugin structure**: "plugin manifest", "directory layout" → plugin-structure skill
- **Settings**: "plugin configuration", ".local.md files" → plugin-settings skill
- **Commands**: "create slash command", "add workflow" → command-development skill
- **Agents**: "create agent", "autonomous tasks" → agent-development skill
- **Skills**: "create skill", "add knowledge" → skill-development skill
- **Marketplaces**: "distribute plugins", "marketplace" → marketplace-structure skill

## Available Commands (Manual Invoke)

- `/plugin-dev:start` - Choose between creating a plugin or marketplace
- `/plugin-dev:create-plugin` - 8-phase guided plugin creation
- `/plugin-dev:create-marketplace` - 8-phase guided marketplace creation

## Available Agents (AI-Assisted)

- **agent-creator**: Generate new agents from descriptions
- **plugin-validator**: Validate plugin structure
- **skill-reviewer**: Review skill quality

## What Would You Like to Do?

Based on your needs, I can:
1. Guide you through creating a complete plugin → `/plugin-dev:start`
2. Load a specific skill for domain knowledge → Ask about the topic
3. Validate your existing plugin → Mention "validate my plugin"
4. Create a specific component → Ask to create it

What would you like to do?

---

Keeping Up with Anthropic's Changes

Regarding the user's question about keeping pace with Claude Code updates:

Your approach is sound. For closed-source tools:

1. Monitor Agent SDK (open source, better docs) for patterns
2. Check Claude Code CHANGELOG for feature announcements
3. Test and experiment with new features as they appear
4. Community engagement - users report issues/discoveries

Additional strategies:

• Version tagging: Tag plugin-dev releases with "tested on Claude Code vX.X.X"
• Deprecation warnings: Add notes when features change (e.g., "Note: As of Claude Code v2.0, skills and commands share format")
• Community contributions: Accept PRs updating docs when users discover changes (like this issue!)

For the specific features mentioned:

• hooks in YAML frontmatter: Test if this works, document in hook-development skill
• fork strategies: Research what this is, add to relevant skills

I can help investigate these if you'd like - would require testing against current Claude Code or checking Agent SDK.

---

Summary

Impact of skills/commands merging on plugin-dev: LOW

The architectural foundation is already sound. The main work is:

1. Documentation clarification (high priority) - explain the relationship in modern Claude Code
2. Meta-skill addition (medium priority) - help new users discover capabilities
3. New features investigation (medium priority) - document hooks frontmatter, fork strategies
4. Enhanced triggering (low priority) - improve skill descriptions

The plugin-dev toolkit is well-positioned for the convergence because it already treats skills and commands as complementary tools with distinct purposes. The "merging" in Claude Code doesn't eliminate those purposes - it just makes the implementation more flexible.

Next Steps:

1. Decide on meta-skill approach (Option A, B, or C)
2. Investigate new Claude Code features (hooks in frontmatter, fork strategies)
3. Update documentation to reflect skills/commands relationship
4. Continue accepting community contributions for Claude Code updates

Happy to help implement any of these changes if you'd like!

---

| Branch: claude/issue-184-20260117-1820

[sjnims]

From Claude.ai:

Impact Assessment: Claude Code 2.1.3 Skills/Commands Merge on plugin-dev

What Changed in 2.1.3

The merge is conceptual, not structural. The key change:

Before	After
Skills = auto-discovered by Claude	Skills can be invoked via / prefix
Commands = explicit /command invocation	Commands are "lightweight Skills"
Separate mental models	Unified system with two triggers

Critical point: "no change in behavior" means your existing directory structure (commands/, skills/) still works. Claude Code still discovers components from those directories the same way.

---

Impact on plugin-dev

✅ Low/No Impact (Keep As-Is)

Your directory structure is fine. Claude Code still expects:

• commands/*.md for slash commands
• skills/*/SKILL.md for skills

Your 8 skills and 3 commands continue to work because the merge doesn't change file locations or loading behavior.

⚠️ Moderate Impact (Documentation Updates Needed)

Your documentation in these skills now contains a partially outdated mental model:

1. command-development skill - The "commands vs skills" distinction it teaches is now blurred. The guidance about "when to use commands" needs revision since skills can now be invoked explicitly too.

2. skill-development skill - Should clarify that skills can now also be invoked via /skill-name syntax, not just through automatic discovery.

3. plugin-structure skill - The "commands/ for explicit invocation, skills/ for auto-discovery" framing is technically still true but no longer the primary differentiator.

---

Recommended Updates

Update the mental model guidance

Update skills to reflect the new unified approach:

## When to Use Commands vs Skills (Post-2.1.3)

Both can be invoked explicitly via `/name`. The real distinctions are now:

| Use **Commands** when... | Use **Skills** when... |
|--------------------------|------------------------|
| Single .md file is sufficient | Need supporting files (scripts, references, examples) |
| Action-oriented (deploy, test, validate) | Knowledge-oriented (how to do X, patterns for Y) |
| Arguments drive behavior (`/deploy prod`) | Context drives behavior (Claude decides relevance) |
| User always invokes explicitly | Claude may invoke automatically when relevant |

Update user-invocable guidance

This field is now more important since it controls whether a skill appears in the / menu:

## user-invocable Field

Controls slash command visibility:
- `true` (default for skills in /skills/): Shows in / menu AND auto-discovered
- `false`: Hidden from / menu, auto-discovered only

---

Specific Files to Update

File	Change Needed
skills/command-development/SKILL.md	Add note about the unified model
skills/skill-development/SKILL.md	Explain skills can now be /-invoked
skills/plugin-structure/SKILL.md	Update the component decision guidance
README.md	Expand "Skills load automatically when you ask relevant questions" language

---

✅ No Action Needed

Your validation agents and the /plugin-dev:create-plugin workflow don't need changes since they guide users through component decisions based on use case, not on the old command/skill dichotomy.

[sjnims]

Implementation Plan

After reviewing the discussion and verifying against official Claude Code documentation, here's what we're implementing:

Skill Tool Documentation Updates

The SlashCommand tool was indeed merged into the Skill tool. Our documentation needs updates:

1. Rename slashcommand-tool.md → skill-tool.md

   • Update all "SlashCommand tool" references to "Skill tool"
   • Update permission syntax: SlashCommand:/command → Skill(command:*)
   • Note that the Skill tool now invokes both commands AND skills

2. Add user-invocable documentation to skill-development skill

   • Document the field (defaults to true)
   • Clarify it only controls slash menu visibility
   • Explain it does NOT affect Skill tool access or auto-discovery

3. Update command-development/SKILL.md

   • Reference the Skill tool instead of SlashCommand tool

Regarding the Meta-Skill (Original Feature Request)

The plugin-dev-guide meta-skill is a separate feature that we'll handle independently. @kylesnowschwartz - would you like to submit a PR with your implementation from your fork? If so, we'd be happy to review it. Otherwise, we can create a follow-up issue to track this enhancement.

---

Starting work on documentation updates now.

[sjnims]

PR #186 submitted for the Skill tool documentation updates.