* improve: enhance skill descriptions for better automatic activation Improved skill descriptions across both plugins to trigger more reliably when users make requests without specifying exact keywords or formats. ## Visual Documentation Plugin Skills All four skills improved to activate regardless of whether users specify HTML: - **flowchart-creator**: Removed "explicitly" and "in HTML format" restrictions Added triggers: "process flows" - **dashboard-creator**: Removed "explicitly" and "in HTML format" restrictions Added triggers: "monitoring interfaces" - **timeline-creator**: Removed "explicitly" and "in HTML format" restrictions Added triggers: "project plans" - **technical-doc-creator**: Removed "explicitly" and "in HTML format" restrictions Added triggers: "API references", "developer documentation" ## Engineering Workflow Plugin Skills All four skills enhanced with additional natural language triggers: - **feature-planning**: Removed "requires planning before implementation" (too restrictive) Added triggers: "create X feature", "I need X" - **test-fixing**: Added triggers: "run tests and fix failures", "tests aren't passing" - **git-pushing**: Added triggers: "push this", "push to github" - **review-implementing**: Added triggers: "fix review issues", "apply these suggestions" ## Testing Artifacts Added comprehensive test examples and sample outputs: - TEST_EXAMPLES.md with detailed test cases for each visual skill - Sample HTML outputs for flowchart and dashboard skills ## Impact Skills will now activate more reliably when users make natural requests without requiring exact phrasing or format specifications. This provides a better user experience and ensures skills are preferred over Claude's built-in knowledge. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add productivity-skills plugin with workflow optimization capabilities Add new productivity-skills plugin containing 4 skills for analyzing usage patterns, auditing code quality, bootstrapping projects, and generating documentation: - conversation-analyzer: Analyzes Claude Code usage patterns and suggests workflow improvements - Includes Python analysis script for comprehensive conversation history analysis - Identifies patterns, common mistakes, and automation opportunities - code-auditor: Comprehensive codebase analysis covering architecture, security, performance - project-bootstrapper: Sets up projects with best practices, tooling, and documentation - codebase-documenter: Generates comprehensive documentation for codebases Also includes: - CLAUDE.md: Development guidelines for building marketplace plugins and skills - Updated marketplace.json with productivity-skills plugin - Analysis scripts and tools bundled with conversation-analyzer skill - Updated .gitignore to exclude local analysis outputs Plugin follows marketplace conventions with proper structure (SKILL.md files, .claude-plugin/plugin.json, README.md, scripts/ and references/ directories). Based on analysis of 900+ Claude Code conversations to identify common workflow optimization needs and productivity patterns. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: enforce skills-first approach in CLAUDE.md guidelines Update development guidelines to make skills usage mandatory rather than optional: - Elevate "Skills first" to #1 priority in working guidelines - Create dedicated "Critical Working Guidelines" section - Add explicit rule: "ALWAYS use skills when available" - Specify concrete examples (git-pushing, feature-planning, test-fixing) - Emphasize: never implement manually when a skill exists This ensures consistent skill usage throughout the marketplace development and reinforces the skills-based workflow for all contributors. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(git-pushing): add smart_commit.sh script for faster workflow Add automated script to speed up git-pushing skill execution: - Auto-stages all changes - Auto-generates conventional commit messages - Determines type (feat/fix/docs/test/chore/refactor) from file patterns - Extracts scope from changed files - Adds Claude Code footer automatically - Smart push handling (new vs existing branches) - Colored output for better UX - Shows PR link for GitHub repos Updated SKILL.md with: - Fast Path (recommended) - uses script for speed - Manual Path (fallback) - step-by-step commands Speed improvement: 1 command instead of 5+ separate bash calls. Script location: engineering-workflow-plugin/skills/git-pushing/scripts/smart_commit.sh 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs(CLAUDE.md): mandate skill-creator usage for new skills Add critical guideline requiring use of skill-creator skill when creating new skills: - Added explicit rule: "Use skill-creator for creating new skills" - Created "CRITICAL: When creating new skills" section - Emphasized that manual creation leads to missing files and incorrect structure - References issue where productivity-skills were created manually without proper structure This prevents future skills from being created with missing skill.json files, incorrect directory structure, or other structural issues. Lesson learned: productivity-skills plugin was created manually and lacks proper skill structure (missing skill.json files in skill directories). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(productivity-skills): correct plugin structure to follow auto-discovery pattern Fix productivity-skills plugin to follow correct Claude Code plugin structure: Structural changes: - Move all skills into skills/ subdirectory (was at plugin root) - Remove skills array from plugin.json (skills are auto-discovered) - plugin.json now contains only metadata (name, version, description, author) Skills moved: - conversation-analyzer → skills/conversation-analyzer - code-auditor → skills/code-auditor - project-bootstrapper → skills/project-bootstrapper - codebase-documenter → skills/codebase-documenter CLAUDE.md updates: - Document that skills MUST be in skills/ subdirectory - Clarify that skills, agents, and commands are auto-discovered - Update plugin.json template to show metadata-only structure - Remove incorrect examples showing skills/agents arrays in plugin.json This follows the official Claude Code plugin structure where skills are automatically discovered from the skills/ directory rather than being listed in plugin.json. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * chore: Restructure of skills, add readme files --------- Co-authored-by: Claude <noreply@anthropic.com>
20 KiB
Claude Code Instructions for Skills Marketplace Development
Repository: claude-skills-marketplace Purpose: Development guidelines for creating high-quality Claude Code skills and plugins
🎯 Repository Context
This is the Claude Skills Marketplace - a collection of reusable skills and plugins for Claude Code. When working in this repository, you are helping develop skills that will be used by many developers.
Current Plugins
-
engineering-workflow-skills (v1.1.0)
- feature-planning, test-fixing, git-pushing, review-implementing
- plan-implementer agent
-
visual-documentation-skills (v1.0.0)
- visual-html-creator for stunning HTML documentation
-
productivity-skills (v1.0.0)
- conversation-analyzer, code-auditor, project-bootstrapper, codebase-documenter
🏗️ Plugin Structure Standards
Required Directory Structure
{plugin-name}-plugin/
├── .claude-plugin/
│ └── plugin.json # REQUIRED: Plugin metadata ONLY (no skills array)
├── skills/ # Skills directory (auto-discovered)
│ └── {skill-name}/
│ ├── SKILL.md # REQUIRED: Skill specification
│ ├── references/ # OPTIONAL: Reference materials (markdown)
│ │ └── *.md # Additional context/guides
│ └── scripts/ # OPTIONAL: Helper scripts
│ └── *.py # Python scripts, shell scripts, etc.
├── agents/ # OPTIONAL: Agents directory (auto-discovered)
│ └── {agent-name}/
│ └── AGENT.md # Agent specification
├── commands/ # OPTIONAL: Commands directory (auto-discovered)
│ └── {command-name}.md
├── README.md # REQUIRED: Plugin documentation
├── CHANGELOG.md # RECOMMENDED: Version history
└── EXAMPLES.md # RECOMMENDED: Usage examples
CRITICAL: Skills are auto-discovered!
- Skills MUST be in
skills/subdirectory at plugin root - Skills are automatically discovered - NO listing in plugin.json
- plugin.json contains ONLY metadata (name, version, description, author)
- Same applies to agents/ and commands/ - all auto-discovered
Directory purposes:
skills/- All skills (auto-discovered from SKILL.md files)agents/- All agents (auto-discovered from AGENT.md files)commands/- All commands (auto-discovered from .md files)references/- Markdown documentation, guides, best practicesscripts/- Executable scripts (Python, shell, etc.) that skills can use
Critical Files
1. .claude-plugin/plugin.json
Location matters! Must be in .claude-plugin/ subdirectory, not at root.
{
"name": "example-skills",
"version": "1.0.0",
"description": "Clear, concise description of what the plugin provides",
"author": {
"name": "author-name"
}
}
Key points:
- ONLY metadata - name, version, description, author
- NO skills array - skills are auto-discovered from skills/ directory
- NO agents array - agents are auto-discovered from agents/ directory
- NO commands array - commands are auto-discovered from commands/ directory
- Keep it simple - just plugin metadata!
2. SKILL.md
Every skill MUST have a SKILL.md file. This is the instruction set for Claude.
Required sections:
# {Skill Name}
## Purpose
Clear statement of what this skill does and why it exists.
## When to Use
List of scenarios where this skill is appropriate.
**Activation phrases:**
- "phrase that triggers this skill"
- "another trigger phrase"
- "third example"
## What It Does
Detailed explanation of the skill's workflow:
1. First step
2. Second step
3. etc.
## Approach
How the skill should approach the task, including:
- Analysis strategy
- Tool usage patterns
- Decision-making criteria
- Error handling
## Example Interaction
User: "example request"
Skill:
- Does X
- Asks Y
- Implements Z
## Tools Used
- **ToolName**: Why and when to use it
- **AnotherTool**: Purpose
## Success Criteria
How to know when the skill has succeeded:
- Criterion 1
- Criterion 2
## Integration
How this skill works with other skills (if applicable).
Best practices for SKILL.md:
- Be specific about activation phrases
- Include concrete examples
- Explain the "why" not just the "what"
- Mention tool usage patterns
- Define success criteria clearly
- Use realistic example interactions
3. README.md
Plugin README should be user-facing documentation:
# {Plugin Name}
Brief description of what the plugin provides.
## Skills Included
### 1. Skill Name
**Purpose:** What it does
**Activates when you say:**
- "trigger phrase"
- "another phrase"
**What it does:**
- Feature 1
- Feature 2
**Example:**
User: "example" Claude: [does X, Y, Z]
## Installation
Instructions for installing the plugin.
## Usage Tips
How to get the best results from these skills.
## Integration
How skills work together or with other plugins.
## Version
Current version number.
## Author
Author information.
🎨 Skill Design Principles
1. Automatic Activation
Skills should activate based on natural language intent, not explicit invocation.
Good activation triggers:
"audit the code" → code-auditor
"set up this project" → project-bootstrapper
"fix the tests" → test-fixing
Bad (requiring explicit invocation):
"/audit" → Too manual
"run code-auditor" → Not natural
2. Clear Scope
Each skill should have a single, well-defined purpose.
Good (focused):
test-fixing: Fix failing testsgit-pushing: Handle git operationscode-auditor: Audit code quality
Bad (too broad):
do-everything: Multiple unrelated functionsdeveloper-helper: Vague purpose
3. Tool-Rich Implementation
Skills should leverage all available tools effectively:
- Read: File analysis
- Write/Edit: Code changes
- Grep/Glob: Pattern matching and file discovery
- Bash: Execute commands, run tests
- Task (agents): Delegate complex sub-tasks
- AskUserQuestion: Gather requirements
Example from code-auditor:
1. Use Explore agent for thorough codebase mapping
2. Use Grep for pattern detection (security issues, TODOs)
3. Use Read for detailed file analysis
4. Use Bash to run linters/analyzers if available
5. Synthesize findings into report
4. User Interaction
When to ask vs. when to proceed:
ASK when:
- Multiple valid approaches exist (technology choices, architectural decisions)
- Requirements are ambiguous
- User preference matters (depth of analysis, output format)
- Potentially destructive operations
PROCEED when:
- Best practice is clear
- Request has sufficient context
- Operation is safe and reversible
- Asking would slow down unnecessarily
Use AskUserQuestion for structured choices:
Questions:
- "Which testing framework?"
Options: pytest, unittest, nose2
- "Deployment target?"
Options: Docker, AWS Lambda, Traditional server
5. Comprehensive Documentation
Skills should be self-documenting:
- Explain what they're doing as they work
- Provide file:line references for all findings
- Summarize results clearly
- Suggest next steps
Good example:
"I've analyzed the codebase and found 3 security issues:
1. SQL injection risk in database/query.py:45
- Uses string concatenation for queries
- Recommendation: Use parameterized queries
2. Hardcoded credentials in config/settings.py:12
- API key visible in code
- Recommendation: Use environment variables
3. Missing input validation in api/users.py:78
- User input directly used in file paths
- Recommendation: Add path sanitization
Priority: Fix item 1 (critical) immediately."
🔨 Creating a New Skill
Step 1: Plan
Before coding, define:
- Purpose: What problem does this solve?
- Activation: What phrases trigger it?
- Scope: What's included/excluded?
- Tools: Which tools will it use?
- Integration: How does it work with existing skills?
Step 2: Create Structure
# In existing plugin or create new
mkdir -p {plugin-name}-plugin/.claude-plugin
mkdir -p {plugin-name}-plugin/{skill-name}
# Create files
touch {plugin-name}-plugin/.claude-plugin/plugin.json
touch {plugin-name}-plugin/{skill-name}/SKILL.md
touch {plugin-name}-plugin/README.md
Step 3: Write SKILL.md
Start with the template above. Be specific about:
- When to activate (trigger phrases)
- What to do (step-by-step workflow)
- How to do it (tool usage patterns)
- Success criteria (when is it done?)
Step 4: Update plugin.json
Add your skill to the skills array:
{
"name": "skill-name",
"source": "./skill-directory",
"description": "Activates when users [trigger phrase]. Does [what it does].",
"gitignored": false,
"project": false
}
Step 5: Document
Create/update README.md with:
- Skill purpose and benefits
- Activation examples
- Usage tips
- Integration notes
Step 6: Test
Test the skill with various inputs:
- ✅ Natural activation phrases
- ✅ Edge cases
- ✅ Error conditions
- ✅ Integration with other skills
Step 7: Add to Marketplace
Update .claude-plugin/marketplace.json:
{
"plugins": [
{
"name": "your-plugin-name",
"source": "./your-plugin-directory",
"description": "Clear description",
"version": "1.0.0",
"author": {
"name": "your-name"
}
}
]
}
📚 Reference Materials
Skills can include reference materials in references/ directory:
skill-name/
├── SKILL.md
└── references/
├── best-practices.md # Industry best practices
├── examples.md # Code examples
├── patterns.md # Design patterns
└── troubleshooting.md # Common issues
Claude can read these during skill execution for additional context.
When to use references:
- Detailed technical specifications
- Code examples and templates
- Best practices guides
- Troubleshooting information
- Pattern libraries
Examples from existing skills:
visual-html-creator/references/design_patterns.md- Design patterns for visual docsvisual-html-creator/references/svg_library.md- SVG component libraryfeature-planning/references/planning-best-practices.md- Planning guide
🤖 Creating Agents
Agents are specialized sub-agents with specific purposes.
Agent Structure
agents/
└── {agent-name}/
└── AGENT.md
AGENT.md Template
# {Agent Name}
## Purpose
What this agent specializes in.
## When to Use
Scenarios where this agent should be invoked.
## Capabilities
What this agent can do:
- Capability 1
- Capability 2
## Approach
How the agent should work:
1. Step 1
2. Step 2
## Tools
Tools this agent has access to.
## Constraints
What this agent should NOT do.
## Output
What this agent should return.
Agent Best Practices
- Focused purpose: Agents should have narrow, well-defined scope
- Clear constraints: Explicitly state what agent should NOT do
- Efficient model: Use Haiku for cost-effective execution when possible
- Clear output: Define what agent should return to parent skill
Example from plan-implementer:
- Purpose: Implement code from detailed plans
- Model: claude-3-5-haiku (cost-effective)
- Constraints: No feature creep, stick to plan
- Output: Working implementation with tests
🎯 Quality Standards
Required Elements
Every skill must have:
- ✅ Clear purpose statement
- ✅ Specific activation phrases
- ✅ Step-by-step approach
- ✅ Tool usage specification
- ✅ Success criteria
- ✅ Example interactions
- ✅ User-facing documentation
Best Practices
- Descriptive names:
code-auditornotchecker - Natural activation: Match how users naturally phrase requests
- Tool-rich: Use multiple tools effectively
- Well-documented: Both in SKILL.md and README
- Integration-aware: Know how to work with other skills
- Error-resilient: Handle edge cases gracefully
- User-friendly: Explain what's happening, provide clear output
Common Pitfalls to Avoid
❌ Too broad: Skill tries to do too many unrelated things ❌ Manual activation: Requires slash command or explicit invocation ❌ Tool-poor: Only uses basic tools, doesn't leverage full toolkit ❌ Undocumented: Unclear when/how to use ❌ Silent: Doesn't explain what it's doing ❌ Isolated: Doesn't integrate with other skills ❌ Vague: Unclear success criteria or output
📦 Version Management
Semantic Versioning
Use semantic versioning: MAJOR.MINOR.PATCH
- MAJOR: Breaking changes to skill interface
- MINOR: New features, backward compatible
- PATCH: Bug fixes, no new features
CHANGELOG.md
Maintain a changelog:
# Changelog
## [1.1.0] - 2025-10-22
### Added
- New skill: feature-planning
- Agent: plan-implementer
### Changed
- Improved git-pushing commit messages
### Fixed
- Bug in test-fixing error grouping
## [1.0.0] - 2025-10-15
### Added
- Initial release with 4 skills
🔄 Workflow for Updates
Adding a New Skill to Existing Plugin
- Create skill directory and SKILL.md
- Update plugin.json (add to skills array)
- Update README.md (document new skill)
- Update CHANGELOG.md (note addition)
- Increment version (MINOR version bump)
- Test activation and functionality
- Commit with descriptive message
Creating a New Plugin
- Create plugin directory structure
- Create
.claude-plugin/plugin.json - Create initial skill(s)
- Create README.md and CHANGELOG.md
- Update marketplace.json
- Test thoroughly
- Document in main README if appropriate
- Commit and create PR if sharing
🧪 Testing Checklist
Before considering a skill complete:
- SKILL.md includes all required sections
- Activation phrases are natural and clear
- Tool usage is comprehensive and appropriate
- Success criteria are well-defined
- README.md documents the skill for users
- plugin.json correctly references the skill
- Works with natural language activation
- Handles edge cases gracefully
- Integrates well with related skills
- Example interactions are realistic
- Reference materials included if needed
- Version updated appropriately
- CHANGELOG updated
💡 Skill Ideas & Patterns
Analysis Skills Pattern
Skills that analyze and report:
- Explore thoroughly first
- Use multiple analysis dimensions
- Provide specific findings with file:line references
- Prioritize recommendations
- Include both quick wins and long-term improvements
Examples: code-auditor, conversation-analyzer
Setup/Bootstrap Skills Pattern
Skills that configure or initialize:
- Ask clarifying questions upfront
- Show plan before executing
- Work systematically through areas
- Explain each change
- Provide post-setup guidance
Examples: project-bootstrapper
Documentation Skills Pattern
Skills that generate documentation:
- Explore to understand structure
- Create comprehensive coverage
- Include visual elements (diagrams)
- Provide concrete examples
- Make navigable and organized
Examples: codebase-documenter, visual-html-creator
Workflow Automation Pattern
Skills that handle repetitive workflows:
- Minimize user input required
- Follow best practices automatically
- Handle edge cases
- Provide clear status/results
- Integrate with related workflows
Examples: git-pushing, test-fixing
🎓 Learning from Existing Skills
Study These Examples
Best activation phrases:
- Look at engineering-workflow-skills for natural triggers
- Notice how they match common developer requests
Best tool usage:
- code-auditor: Comprehensive tool orchestration
- feature-planning: Effective use of AskUserQuestion
- plan-implementer: Focused agent with clear constraints
Best documentation:
- visual-documentation-skills: Excellent README structure
- productivity-skills: Clear activation examples
Best integration:
- feature-planning + plan-implementer: Skill → Agent handoff
- All engineering-workflow skills: Complementary capabilities
🚀 When Working on This Repository
Your Role
You are helping develop high-quality, reusable skills for the Claude Code community.
Priorities:
- Skills first: ALWAYS use available skills before manual implementation
- Quality over speed: Take time to design well
- User experience: Natural activation, clear output
- Documentation: Both technical (SKILL.md) and user-facing (README)
- Integration: Consider how skills work together
- Standards: Follow established patterns and structure
Critical Working Guidelines
1. ALWAYS use skills when available
For ANY task in this repository:
- Check if a skill can handle it FIRST
- Use git-pushing for all git operations
- Use feature-planning for complex features
- Use test-fixing for test failures
- Use skill-creator for creating new skills - ensures proper structure
- Never implement manually when a skill exists
CRITICAL: When creating new skills:
- ALWAYS use the skill-creator skill from example-skills
- Never manually create skill structure
- skill-creator ensures all required files and structure are correct
- Manual creation often leads to missing files (skill.json, proper directories, etc.)
2. NEVER create markdown files unless explicitly requested by the user.
This includes:
- ❌ Don't create README.md, CHANGELOG.md, or other docs proactively
- ❌ Don't create example files or guides without being asked
- ❌ Don't create markdown documentation as a "helpful addition"
- ✅ Only create .md files when the user specifically requests them
- ✅ Focus on code and functionality first, documentation when asked
Exception: When creating a new skill/plugin per user request, the required files (SKILL.md, plugin.json, README.md) are part of the deliverable and should be created.
Making Changes
When adding features:
- Understand the existing pattern
- Design before implementing
- Follow structure conventions
- Document thoroughly
- Update version and changelog
- Test comprehensively
When improving existing skills:
- Read SKILL.md fully to understand intent
- Maintain backward compatibility if possible
- Update documentation
- Test that existing use cases still work
- Version bump appropriately
Code Quality
For SKILL.md files:
- Clear, concise language
- Specific instructions, not vague guidelines
- Concrete examples
- Realistic scenarios
For reference materials:
- Well-organized
- Comprehensive but focused
- Practical examples
- Up-to-date best practices
📋 Quick Reference
File Locations (Critical!)
✅ CORRECT:
plugin-name-plugin/.claude-plugin/plugin.json
plugin-name-plugin/skill-name/SKILL.md
❌ WRONG:
plugin-name-plugin/plugin.json # Wrong location
plugin-name-plugin/skill-name/README.md # Wrong filename (use SKILL.md)
Skill Naming
- Use kebab-case:
code-auditor,feature-planning - Be descriptive:
test-fixingnotfixer - Match purpose: Name should indicate what it does
Description Writing
In plugin.json: Focus on when it activates and what it does:
"description": "Activates when users want to [trigger]. Provides [benefit]."
In SKILL.md: Focus on how it works and detailed approach.
In README.md: Focus on user benefits and practical examples.
🎁 Remember
You're building tools that developers will use every day.
Make them:
- 🎯 Purposeful - Clear, focused scope
- 🗣️ Natural - Activate with natural language
- 🔧 Powerful - Leverage all available tools
- 📖 Well-documented - Easy to understand and use
- 🤝 Integrated - Work well with other skills
- ✨ Delightful - Make developers' lives easier
This repository analysis is based on existing plugins: engineering-workflow-skills, visual-documentation-skills, and productivity-skills.