personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: extract skills from commands across 8 plugins

Browse Source 
Refactored commands to extract reusable skills following the
Commands → Skills separation pattern. Each command is now <50 lines
and references skill files for detailed knowledge.

Plugins refactored:
- claude-config-maintainer: 5 commands → 7 skills
- code-sentinel: 3 commands → 2 skills
- contract-validator: 5 commands → 6 skills
- data-platform: 10 commands → 6 skills
- doc-guardian: 5 commands → 6 skills (replaced nested dir)
- git-flow: 8 commands → 7 skills

Skills contain: workflows, validation rules, conventions,
reference data, tool documentation

Commands now contain: YAML frontmatter, agent assignment,
skills list, brief workflow steps, parameters

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-30 17:32:24 -05:00
parent aad02ef2d9
commit 7c8a20c804
71 changed files with 3896 additions and 3690 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
plugins/claude-config-maintainer/skills/analysis-workflow.md Normal file
View File

@@ -0,0 +1,112 @@
# CLAUDE.md Analysis Workflow
This skill defines the workflow for analyzing CLAUDE.md files.
## Analysis Steps
1. **Locate File** - Find CLAUDE.md in project root
2. **Parse Structure** - Extract headers and sections
3. **Evaluate Content** - Score against criteria
4. **Detect Plugins** - Identify active marketplace plugins
5. **Check Integration** - Verify plugin references
6. **Generate Report** - Provide scored assessment
## Content Analysis
### What to Check
| Area | Check For |
|------|-----------|
| Structure | Header hierarchy, section ordering, grouping |
| Clarity | Clear instructions, examples, unambiguous language |
| Completeness | Required sections present, workflows documented |
| Conciseness | No redundancy, efficient density, appropriate length |
### Required Sections Check
1. Project Overview - present?
2. Quick Start - present with commands?
3. Critical Rules - present?
4. **Pre-Change Protocol** - present? (HIGH PRIORITY if missing)
## Plugin Integration Analysis
### Detection Method
1. Read `.claude/settings.local.json` for enabled MCP servers
2. Map MCP servers to plugins:
- `gitea` -> projman
- `netbox` -> cmdb-assistant
3. Check for hook-based plugins (project-hygiene)
4. Scan CLAUDE.md for plugin references
### Coverage Scoring
For each detected plugin, verify CLAUDE.md contains:
- Plugin section header or mention
- Available commands documentation
- MCP tools reference (if applicable)
- Usage guidelines
Coverage = (plugins referenced / plugins detected) * 100%
## Report Format
```
CLAUDE.md Analysis Report
=========================
File: /path/to/project/CLAUDE.md
Lines: N
Last Modified: YYYY-MM-DD
Overall Score: NN/100
Category Scores:
- Structure: NN/25 (Rating)
- Clarity: NN/25 (Rating)
- Completeness: NN/25 (Rating)
- Conciseness: NN/25 (Rating)
Strengths:
+ [Positive finding]
Issues Found:
N. [SEVERITY] Issue description (location)
Context explaining the problem.
Impact: What happens if not fixed.
Recommendations:
N. Action to take (priority: high/medium/low)
---
Plugin Integration Analysis
===========================
Detected Active Plugins:
[check] plugin-name (via detection method)
Plugin Coverage: NN% (N/N plugins referenced)
Missing Integration Content:
N. plugin-name
What to add.
```
## Issue Severity
| Level | When to Use |
|-------|-------------|
| HIGH | Missing mandatory sections, security issues |
| MEDIUM | Missing recommended content, duplicate content |
| LOW | Formatting issues, minor improvements |
## Follow-Up Actions
After analysis, offer:
1. Implement all content recommendations
2. Add missing plugin integrations
3. Do both (recommended)
4. Show preview of changes first

113
plugins/claude-config-maintainer/skills/claude-md-structure.md Normal file
View File

@@ -0,0 +1,113 @@
# CLAUDE.md Structure Reference
This skill defines the standard structure, required sections, and templates for CLAUDE.md files.
## Required Sections
Every CLAUDE.md MUST have these sections:
| Section | Purpose | Priority |
|---------|---------|----------|
| Project Overview | What the project does | Required |
| Quick Start | Build/test/run commands | Required |
| Critical Rules | Must-follow constraints | Required |
| Pre-Change Protocol | Dependency check before edits | **MANDATORY** |
## Recommended Sections
| Section | When to Include |
|---------|-----------------|
| Architecture | Complex projects with multiple components |
| Common Operations | Projects with repetitive tasks |
| File Structure | Large codebases |
| Troubleshooting | Projects with known gotchas |
| Integration Points | Projects with external dependencies |
## Header Hierarchy
```
# CLAUDE.md (H1 - only one)
## Section (H2 - main sections)
### Subsection (H3 - within sections)
#### Detail (H4 - rarely needed)
```
**Rules:**
- Never skip levels (no H3 before H2)
- Maximum depth: 4 levels
- No orphaned content before first header
## Templates
### Minimal Template
For small projects:
```markdown
# CLAUDE.md
## Project Overview
[Description]
## Quick Start
[Commands]
## Critical Rules
[Constraints]
## Pre-Change Protocol
[Mandatory section - see pre-change-protocol.md]
```
### Standard Template (Default)
```markdown
# CLAUDE.md
## Project Overview
## Quick Start
## Architecture
## Critical Rules
## Pre-Change Protocol
## Common Operations
## File Structure
```
### Comprehensive Template
For large projects - adds:
- Detailed Architecture
- Troubleshooting
- Integration Points
- Development Workflow
- Deployment Notes
## Auto-Detection Signals
| Technology | Detection Method |
|------------|------------------|
| Language | File extensions, config files |
| Framework | package.json, requirements.txt, Cargo.toml |
| Build system | Makefile, scripts in package.json |
| Testing | pytest.ini, jest.config.js, go.mod |
| Docker | Dockerfile, docker-compose.yml |
| Database | ORM configs, connection strings |
## Section Content Guidelines
### Project Overview
- 1-3 sentences describing purpose
- Target audience if relevant
- Key technologies used
### Quick Start
- Install command
- Test command
- Run command
- Each with brief inline comment
### Critical Rules
- Numbered or bulleted list
- Specific, actionable constraints
- Include rationale for non-obvious rules
### Architecture
- High-level component diagram (ASCII or description)
- Data flow explanation
- Key file/directory purposes

97
plugins/claude-config-maintainer/skills/diff-analysis.md Normal file
View File

@@ -0,0 +1,97 @@
# CLAUDE.md Diff Analysis
This skill defines how to analyze and present CLAUDE.md differences.
## Comparison Modes
| Mode | Command | Description |
|------|---------|-------------|
| Working vs HEAD | `/config-diff` | Uncommitted changes |
| Working vs Commit | `--commit=REF` | Changes since specific point |
| Commit to Commit | `--from=X --to=Y` | Historical comparison |
| Branch Comparison | `--branch=NAME` | Cross-branch differences |
## Change Indicators
| Symbol | Meaning |
|--------|---------|
| `+` | Line added |
| `-` | Line removed |
| `@@` | Location marker (line numbers) |
| `[MODIFIED]` | Section has changes |
| `[ADDED]` | New section created |
| `[REMOVED]` | Section deleted |
| `[UNCHANGED]` | No changes to section |
## Impact Categories
| Category | Meaning |
|----------|---------|
| NEW REQUIREMENT | Claude will need to do something new |
| REMOVED REQUIREMENT | Claude no longer needs to do something |
| MODIFIED | Existing behavior changed |
| NEW RULE | New constraint added |
| RELAXED RULE | Constraint removed or softened |
## Report Format
```
CLAUDE.md Diff Report
=====================
File: /path/to/project/CLAUDE.md
Comparing: [mode description]
Commit: [ref] "[message]" (time ago)
Summary:
- Lines added: N
- Lines removed: N
- Net change: +/-N lines
- Sections affected: N
Section Changes:
----------------
## Section Name [STATUS]
+/- Change description
Detailed Diff:
--------------
--- CLAUDE.md (before)
+++ CLAUDE.md (after)
@@ -N,M +N,M @@
context
-removed
+added
context
Behavioral Impact:
------------------
These changes will affect Claude's behavior:
N. [CATEGORY] Description of impact
```
## Section-Focused View
When using `--section=NAME`:
- Filter diff to only that section
- Show section-specific statistics
- Highlight behavioral impact for that area
## Troubleshooting
### No changes detected
- File matches comparison target
- Verify comparing correct commits
### File not found in commit
- CLAUDE.md didn't exist at that point
- Use `git log -- CLAUDE.md` to find creation
### Not a git repository
- Command requires git history
- Initialize git or use file backup comparison

136
plugins/claude-config-maintainer/skills/lint-rules.md Normal file
View File

@@ -0,0 +1,136 @@
# CLAUDE.md Lint Rules
This skill defines all linting rules for validating CLAUDE.md files.
## Rule Categories
### Security Rules (SEC)
| Rule | Description | Severity | Auto-fix |
|------|-------------|----------|----------|
| SEC001 | Hardcoded absolute paths | Warning | Yes |
| SEC002 | Potential secrets/API keys | Error | No |
| SEC003 | Hardcoded IP addresses | Warning | No |
| SEC004 | Exposed credentials patterns | Error | No |
| SEC005 | Hardcoded URLs with tokens | Error | No |
| SEC006 | Environment variable values (not names) | Warning | No |
### Structure Rules (STR)
| Rule | Description | Severity | Auto-fix |
|------|-------------|----------|----------|
| STR001 | Missing required sections | Error | Yes |
| STR002 | Invalid header hierarchy (h3 before h2) | Warning | Yes |
| STR003 | Orphaned content before first header | Info | No |
| STR004 | Excessive nesting depth (>4 levels) | Warning | No |
| STR005 | Empty sections | Warning | Yes |
| STR006 | Missing section content | Warning | No |
### Content Rules (CNT)
| Rule | Description | Severity | Auto-fix |
|------|-------------|----------|----------|
| CNT001 | Contradictory instructions | Error | No |
| CNT002 | Vague or ambiguous rules | Warning | No |
| CNT003 | Overly long sections (>100 lines) | Info | No |
| CNT004 | Duplicate content | Warning | No |
| CNT005 | TODO/FIXME in production config | Warning | No |
| CNT006 | Outdated version references | Info | No |
| CNT007 | Broken internal links | Warning | No |
### Format Rules (FMT)
| Rule | Description | Severity | Auto-fix |
|------|-------------|----------|----------|
| FMT001 | Inconsistent header styles | Info | Yes |
| FMT002 | Inconsistent list markers | Info | Yes |
| FMT003 | Missing code block language | Info | Yes |
| FMT004 | Trailing whitespace | Info | Yes |
| FMT005 | Missing blank lines around headers | Info | Yes |
| FMT006 | Inconsistent indentation | Info | Yes |
### Best Practice Rules (BPR)
| Rule | Description | Severity | Auto-fix |
|------|-------------|----------|----------|
| BPR001 | No Quick Start section | Warning | No |
| BPR002 | No Critical Rules section | Warning | No |
| BPR003 | Instructions without examples | Info | No |
| BPR004 | Commands without explanation | Info | No |
| BPR005 | Rules without rationale | Info | No |
| BPR006 | Missing plugin integration docs | Info | No |
## Anti-Pattern Examples
### SEC002: Hardcoded Secrets
```markdown
# BAD
API_KEY=sk-1234567890abcdef
# GOOD
API_KEY=$OPENAI_API_KEY # Set via environment
```
### SEC001: Hardcoded Paths
```markdown
# BAD
Config file: /home/john/projects/myapp/config.yml
# GOOD
Config file: ./config.yml
Config file: $PROJECT_ROOT/config.yml
```
### CNT001: Contradictory Rules
```markdown
# BAD
- Always use TypeScript
- JavaScript files are acceptable for scripts
# GOOD
- Always use TypeScript for source code
- JavaScript (.js) is acceptable only for config files and scripts
```
### CNT002: Vague Instructions
```markdown
# BAD
- Be careful with the database
# GOOD
- Never run DELETE without WHERE clause
- Always backup before migrations
```
### STR002: Invalid Hierarchy
```markdown
# BAD
# Main Title
### Skipped Level
# GOOD
# Main Title
## Section
### Subsection
```
## Output Format
```
[SEVERITY] RULE_ID: Description (line N)
| Context line showing issue
| ^^^^^^ indicator
+-- Explanation of problem
Suggested fix:
- old line
+ new line
```
## Severity Levels
| Level | Meaning | Action |
|-------|---------|--------|
| Error | Must fix | Blocks commit |
| Warning | Should fix | Review recommended |
| Info | Consider fixing | Optional improvement |

136
plugins/claude-config-maintainer/skills/optimization-patterns.md Normal file
View File

@@ -0,0 +1,136 @@
# CLAUDE.md Optimization Patterns
This skill defines patterns for optimizing CLAUDE.md files.
## Optimization Categories
### Restructure
- Reorder sections by importance (Quick Start near top)
- Group related content together
- Improve header hierarchy
- Add navigation aids (TOC for long files)
### Condense
- Remove redundant explanations
- Convert verbose text to bullet points
- Eliminate duplicate content
- Shorten overly detailed sections
### Enhance
- Add missing essential sections
- **Add Pre-Change Protocol if missing (HIGH PRIORITY)**
- Improve unclear instructions
- Add helpful examples
- Highlight critical rules
### Format
- Standardize header styles (no trailing colons)
- Fix code block formatting (add language tags)
- Align list formatting (consistent markers)
- Improve table layouts
## Scoring Criteria
### Structure (25 points)
- Logical section ordering
- Clear header hierarchy
- Easy navigation
- Appropriate grouping
### Clarity (25 points)
- Clear instructions
- Good examples
- Unambiguous language
- Appropriate detail level
### Completeness (25 points)
- Project overview present
- Quick start commands documented
- Critical rules highlighted
- Key workflows covered
- Pre-Change Protocol present (MANDATORY)
### Conciseness (25 points)
- No unnecessary repetition
- Efficient information density
- Appropriate length for project size
- No generic filler content
## Score Interpretation
| Score | Rating | Action |
|-------|--------|--------|
| 90-100 | Excellent | Maintenance only |
| 70-89 | Good | Minor improvements |
| 50-69 | Needs Work | Optimization recommended |
| Below 50 | Poor | Major restructuring needed |
## Common Optimizations
### Verbose to Concise
```markdown
# Before (34 lines)
## Running Tests
To run the tests, you first need to make sure you have all the
dependencies installed. The dependencies are listed in requirements.txt.
Once you have installed the dependencies, you can run the tests using
pytest. Pytest will automatically discover all test files...
# After (8 lines)
## Running Tests
```bash
pip install -r requirements.txt # Install dependencies
pytest # Run all tests
pytest -v # Verbose output
pytest tests/unit/ # Run specific directory
```
```
### Duplicate Removal
- Keep first occurrence
- Add cross-reference if needed: "See [Section Name] above"
### Header Standardization
```markdown
# Before
## Quick Start:
## Architecture
## Testing:
# After
## Quick Start
## Architecture
## Testing
```
### Code Block Enhancement
```markdown
# Before
```
npm install
npm test
```
# After
```bash
npm install # Install dependencies
npm test # Run test suite
```
```
## Safety Features
### Backup Creation
- Always backup before changes
- Store in `.claude/backups/CLAUDE.md.TIMESTAMP`
- Easy restoration if needed
### Preview Mode
- Show all changes before applying
- Use diff format for easy review
- Allow approve/reject per change
### Selective Application
- Can apply individual changes
- Skip specific optimizations
- Iterative refinement supported

83
plugins/claude-config-maintainer/skills/pre-change-protocol.md Normal file
View File

@@ -0,0 +1,83 @@
# Pre-Change Protocol
This skill defines the mandatory Pre-Change Protocol section that MUST be included in every CLAUDE.md file.
## Why This Is Mandatory
The Pre-Change Protocol prevents the #1 cause of bugs from AI-assisted coding: **incomplete changes where Claude modifies some files but misses others that reference the same code**.
Without this protocol:
- Claude may rename a function but miss callers
- Claude may modify a config but miss documentation
- Claude may update a schema but miss dependent code
## Detection
Search CLAUDE.md for these indicators:
- Header containing "Pre-Change" or "Before Any Code Change"
- References to `grep -rn` or impact search
- Checklist with "Files That Will Be Affected"
- User verification checkpoint
## Required Section Content
```markdown
## MANDATORY: Before Any Code Change
**Claude MUST show this checklist BEFORE editing any file:**
### 1. Impact Search Results
Run and show output of:
```bash
grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"
```
### 2. Files That Will Be Affected
Numbered list of every file to be modified, with the specific change for each.
### 3. Files Searched But Not Changed (and why)
Proof that related files were checked and determined unchanged.
### 4. Documentation That References This
List of docs that mention this feature/script/function.
**User verifies this list before Claude proceeds. If Claude skips this, stop immediately.**
### After Changes
Run the same grep and show results proving no references remain unaddressed.
```
## Placement
Insert Pre-Change Protocol section:
- **After:** Critical Rules section
- **Before:** Common Operations section
## If Missing During Analysis
Flag as **HIGH PRIORITY** issue:
```
1. [HIGH] Missing Pre-Change Protocol section
CLAUDE.md lacks mandatory dependency-check protocol.
Impact: Claude may miss file references when making changes,
leading to broken dependencies and incomplete updates.
Recommendation: Add Pre-Change Protocol section immediately.
This is the #1 cause of cascading bugs from incomplete changes.
```
## If Missing During Optimization
**Automatically add the section** at the correct position. This is the highest priority enhancement.
## Variations
The exact wording can vary, but these elements are required:
1. **Search requirement** - Must run grep/search before changes
2. **Affected files list** - Must enumerate all files to modify
3. **Non-affected files proof** - Must show what was checked but unchanged
4. **Documentation check** - Must list referencing docs
5. **User checkpoint** - Must pause for user verification
6. **Post-change verification** - Must verify after changes

52
plugins/claude-config-maintainer/skills/visual-header.md Normal file
View File

@@ -0,0 +1,52 @@
# Visual Header Display
This skill defines the standard visual header for claude-config-maintainer commands.
## Header Format
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - [Command Name] |
+-----------------------------------------------------------------+
```
## Command-Specific Headers
### /config-analyze
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - CLAUDE.md Analysis |
+-----------------------------------------------------------------+
```
### /config-optimize
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - CLAUDE.md Optimization |
+-----------------------------------------------------------------+
```
### /config-lint
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - CLAUDE.md Lint |
+-----------------------------------------------------------------+
```
### /config-diff
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - CLAUDE.md Diff |
+-----------------------------------------------------------------+
```
### /config-init
```
+-----------------------------------------------------------------+
| CONFIG-MAINTAINER - CLAUDE.md Initialization |
+-----------------------------------------------------------------+
```
## Usage
Display the header at the start of command execution, before any analysis or output.