Files
mhattingpeteandClaude 474d7555b3 Feat/productivity skills plugin (#8)
* 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>
2025-10-22 20:41:15 +02:00

5.1 KiB

Contributing to Claude Skills Marketplace

Thank you for your interest in contributing! This guide will help you create high-quality Skills that work reliably across different Claude models.

Skill Structure

A basic Skill consists of:

skill-name/
├── SKILL.md          # Required: Main skill file
├── reference.md      # Optional: Detailed reference material
├── examples/         # Optional: Example files or templates
└── scripts/          # Optional: Executable scripts

SKILL.md Format

---
name: skill-name
description: What it does and when to use it. Include activation triggers.
model: sonnet              # Optional: Preferred model (sonnet, opus, haiku)
---

# Skill Title

Brief overview (1-2 sentences).

## When to Use

Specific activation scenarios:
- User says "X"
- Context includes Y
- Task involves Z

## Instructions

Step-by-step instructions for Claude...

Best Practices

1. Write Clear Descriptions

Good:

description: Analyze vendorlist extraction performance and F1-scores. Use when user mentions vendorlist evaluation, low F1-scores, extraction accuracy issues, or asks to analyze vendorlist performance.

Bad:

description: Helps with vendorlists

The description should answer:

  • What does this skill do?
  • When should it activate?
  • Why would someone use it?

2. Use Gerund Names

Good: git-pushing, test-fixing, review-implementing

Bad: git-push, fix-test, implement-review

Gerund forms (-ing) indicate ongoing processes and match natural language patterns.

3. Keep Skills Focused

Each Skill should do ONE thing well. If you find yourself writing "and also" in the description, consider splitting into separate Skills.

4. Structure for Progressive Disclosure

Keep SKILL.md under 500 lines:

  • Core instructions in SKILL.md
  • Detailed reference material in reference.md
  • Examples in separate files

This allows Claude to load only what's needed.

5. Assume Claude's Knowledge

Don't explain basic concepts. Claude already knows Python, git, testing frameworks, etc.

Good:

Run `pytest -k "pattern"` to test specific cases.

Bad:

Pytest is a testing framework for Python. The -k flag filters tests by pattern. You should use this command: `pytest -k "pattern"` to run tests that match the pattern.

6. Match Specificity to Risk

High-risk operations (database migrations, deployments):

  • Provide step-by-step instructions
  • Include validation checks
  • Require confirmation

Low-risk operations (code formatting, documentation):

  • Give general guidance
  • Allow flexibility

7. Use Platform-Agnostic Paths

Good: backend/src/utils/helper.py

Bad: backend\src\utils\helper.py

Always use forward slashes for file paths.

8. Test Across Models

Test your Skill with:

  • Claude Sonnet (balanced)
  • Claude Opus (most capable)
  • Claude Haiku (fastest)

Some models may need more detail than others.

Submission Process

  1. Fork this repository

  2. Create your skill:

    mkdir my-skill
    cd my-skill
    # Create SKILL.md following the template
    
  3. Test thoroughly:

    • Test with different phrasings
    • Verify activation triggers work
    • Check across multiple models if possible
  4. Update README.md:

    • Add your skill to the "Available Skills" section
    • Include activation examples
    • Describe what it does
  5. Submit Pull Request:

    • Title: "Add [skill-name] skill"
    • Description: Explain what the skill does and why it's useful
    • Include example usage

Skill Categories

Organize your skill into one of these categories:

  • Git & Version Control: Git workflows, commits, branches
  • Testing & Quality: Test running, fixing, coverage
  • Code Review: Review feedback, PR management
  • Documentation: Docs generation, README updates
  • DevOps: CI/CD, deployment, infrastructure
  • Data Processing: ETL, analysis, transformation
  • Development Tools: Linting, formatting, refactoring

Examples of Good Skills

Look at existing skills in this repository for inspiration:

  • git-pushing: Clear activation triggers, conventional commits
  • test-fixing: Smart grouping strategy, systematic approach
  • review-implementing: Todo tracking, systematic workflow

Quality Checklist

Before submitting, verify:

  • YAML frontmatter is valid
  • Description includes activation triggers
  • Instructions are concise (no unnecessary explanations)
  • File paths use forward slashes
  • Skill is under 500 lines (or uses reference files)
  • Examples demonstrate activation
  • README.md updated with new skill
  • Tested with actual use cases
  • No hard-coded paths or environment-specific details

Getting Help

Questions or need guidance?

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.