Initial commit

skills/content-optimization-patterns.md

@@ -0,0 +1,413 @@
+---
+title: Content Optimization Patterns
+description: Strategies for reducing verbosity and improving token efficiency in plugin content
+tags: [optimization, verbosity, efficiency, token-usage]
+---
+
+# Content Optimization Patterns
+
+## Metadata
+
+**Purpose**: Guide content optimization for token efficiency without sacrificing clarity
+**Applies to**: All plugin components (agents, skills, commands)
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### Core Optimization Principles
+
+**Balance**: Optimize for clarity AND conciseness, not just brevity
+**Context**: Consider the audience - developers need enough information to act
+**Impact**: Focus on high-impact reductions (not micro-optimizations)
+
+### Common Verbosity Patterns
+
+#### 1. Redundant Section Headers
+
+**Verbose**:
+```markdown
+## What This Command Does
+
+This command validates your documentation against standards.
+
+## Purpose
+
+The purpose of this command is to validate documentation.
+```
+
+**Optimized**:
+```markdown
+## Objective
+
+Validate documentation against standards.
+```
+
+**Savings**: ~30 tokens
+**Risk**: Low - merged sections maintain clarity
+
+#### 2. Repetitive Phrasing
+
+**Verbose**:
+```markdown
+- This skill provides guidance on...
+- This skill helps you understand...
+- This skill contains information about...
+```
+
+**Optimized**:
+```markdown
+- Guidance on...
+- Understanding...
+- Information about...
+```
+
+**Savings**: 10-15 tokens per bullet
+**Risk**: Low - context is clear from structure
+
+#### 3. Over-Explained Examples
+
+**Verbose**:
+```markdown
+**Example**:
+For instance, if you wanted to validate documentation, you would run the following command. This command will analyze your project and output results:
+\```bash
+/validate-docs
+\```
+```
+
+**Optimized**:
+```markdown
+**Example**:
+\```bash
+/validate-docs
+\```
+```
+
+**Savings**: ~25 tokens
+**Risk**: Low if example is self-explanatory
+
+#### 4. Verbose Instructions
+
+**Verbose**:
+```markdown
+You should first read the documentation file, and then after reading it, you need to analyze the contents of that file, and subsequently you must compare it against the standards that have been defined.
+```
+
+**Optimized**:
+```markdown
+1. Read documentation file
+2. Analyze contents
+3. Compare against standards
+```
+
+**Savings**: ~15-20 tokens
+**Risk**: Low - lists are clearer than run-on sentences
+
+#### 5. Redundant "Important" Markers
+
+**Verbose**:
+```markdown
+**IMPORTANT**: This is important to note.
+**NOTE**: Please note the following.
+**WARNING**: Be warned about this.
+```
+
+**Optimized**:
+```markdown
+**Important**: [statement]
+**Note**: [statement]
+**Warning**: [statement]
+```
+
+OR remove if not truly critical:
+```markdown
+[statement]
+```
+
+**Savings**: 5-10 tokens per marker
+**Risk**: Medium - ensure truly important items remain marked
+
+#### 6. Example Bloat
+
+**Verbose**: 10 examples of the same pattern
+
+**Optimized**: 2-3 representative examples, reference pattern
+
+**Savings**: 50-100+ tokens
+**Risk**: Low if examples are truly redundant
+
+#### 7. Meta-Commentary
+
+**Verbose**:
+```markdown
+Now that we have discussed the above concepts, let's move on to the next section where we will explore...
+```
+
+**Optimized**:
+```markdown
+## Next Topic
+```
+
+**Savings**: ~15 tokens per transition
+**Risk**: Low - headings provide structure
+
+### Emoji Usage Guidelines
+
+**When to AVOID emojis** (marketplace standard):
+- Commands: ❌ Professional, concise instructions
+- Skills: ❌ Reference materials for developers
+- Agents: ❌ Expert personas, not casual chatbots
+- Error messages: ❌ Clarity over decoration
+
+**When emojis are acceptable**:
+- User-facing output (if explicitly requested)
+- Documentation examples (sparingly)
+- Celebratory messages (completion confirmations)
+
+**Token cost**: 1-3 tokens per emoji
+**Clarity cost**: Can obscure meaning for screen readers, international audiences
+
+### Redundancy Detection Patterns
+
+#### Cross-Component Redundancy
+
+**Pattern**: Same content in multiple files
+
+**Detection**:
+1. Compare similar sections across files
+2. Look for copy-pasted paragraphs
+3. Check for duplicated templates/examples
+
+**Fix**:
+- Extract to shared skill
+- Reference skill from multiple components
+- Use skill activation instead of inline content
+
+**Example**:
+```markdown
+# Before (in 3 command files)
+## Output Parameters
+- --format=console (default)
+- --format=markdown
+...detailed explanation...
+
+# After
+## Output Parameters
+Activate skill: `marketplace-command-patterns` for standard parameter details.
+```
+
+#### Internal Redundancy
+
+**Pattern**: Same information repeated within a file
+
+**Detection**:
+1. Search for repeated phrases
+2. Look for similar examples
+3. Check for restated concepts
+
+**Fix**:
+- Consolidate duplicate sections
+- Remove redundant examples
+- Use cross-references instead of repetition
+
+### Conciseness Optimization Strategies
+
+#### 1. Active Voice Over Passive
+
+**Verbose**: "The file should be read by the agent"
+**Optimized**: "Agent reads the file"
+**Savings**: ~2-3 tokens per sentence
+
+#### 2. Direct Instructions Over Explanatory
+
+**Verbose**: "You will need to make sure that you..."
+**Optimized**: "Ensure you..."
+**Savings**: ~3-5 tokens per instruction
+
+#### 3. Lists Over Prose
+
+**Verbose**: Paragraph explaining 5 steps
+**Optimized**: Numbered list with 5 items
+**Savings**: 10-20 tokens
+**Clarity**: Improved
+
+#### 4. Tables Over Repeated Structure
+
+**Verbose**: 5 paragraphs with "X does Y, Z is W" pattern
+**Optimized**: Table with X, Y, Z, W columns
+**Savings**: 15-30 tokens
+**Clarity**: Improved
+
+#### 5. Code Over Explanation
+
+**Verbose**: "The JSON file should have a name field, and a description field, and a version field..."
+**Optimized**:
+```json
+{
+  "name": "...",
+  "description": "...",
+  "version": "..."
+}
+```
+**Savings**: 10-15 tokens
+
+### Optimization Decision Framework
+
+Use this framework to decide if optimization is worth it:
+
+```
+Is content redundant or verbose?
+│
+├─ Redundant (duplicated elsewhere)?
+│  ├─ YES → Extract to skill, reference instead (HIGH PRIORITY)
+│  └─ NO → Continue
+│
+├─ Verbose (can be shortened without losing meaning)?
+│  ├─ YES, significant savings (20+ tokens)
+│  │  └─ Does it reduce clarity?
+│  │     ├─ NO → Optimize (MEDIUM PRIORITY)
+│  │     └─ YES → Keep verbose version (clarity wins)
+│  └─ NO → Keep as-is
+│
+└─ Micro-optimization (< 10 token savings)?
+   └─ Skip (not worth the effort)
+```
+
+### Quality Gates
+
+Before optimizing content, ensure:
+- [ ] Meaning is preserved
+- [ ] Examples remain clear
+- [ ] Instructions are still actionable
+- [ ] Technical accuracy maintained
+- [ ] No critical context lost
+
+---
+
+## Resources
+
+### Optimization Checklist
+
+When reviewing content for optimization:
+
+**Redundancy Checks**:
+- [ ] Search for duplicate paragraphs across files
+- [ ] Check for repeated examples
+- [ ] Look for similar explanations in multiple places
+- [ ] Identify extractable patterns
+
+**Verbosity Checks**:
+- [ ] Count section headers (can any be merged?)
+- [ ] Review transition phrases (are they necessary?)
+- [ ] Examine examples (are all needed?)
+- [ ] Check for passive voice
+- [ ] Look for "filler" words (that, very, really, just)
+
+**Structure Checks**:
+- [ ] Can prose become lists?
+- [ ] Can repeated patterns become tables?
+- [ ] Can explanations become code examples?
+- [ ] Are headings descriptive enough to replace intro text?
+
+**Clarity Checks**:
+- [ ] Is technical terminology necessary?
+- [ ] Are instructions actionable?
+- [ ] Do examples illustrate the point?
+- [ ] Is the flow logical?
+
+### Optimization Examples by Component Type
+
+**Agent Optimization**:
+```markdown
+# Before (verbose)
+You are an expert in the field of documentation validation. Your role is to carefully examine documentation files and assess them against predefined standards. You should take a methodical approach to this task.
+
+# After (optimized)
+You are a documentation validation expert. Assess documentation files against predefined standards using a methodical approach.
+```
+
+**Skill Optimization**:
+```markdown
+# Before (redundant)
+## Required Fields
+- name: The name of the plugin
+- version: The version of the plugin
+- description: The description of the plugin
+
+## Plugin Metadata
+- name field contains the plugin name
+- version field contains the plugin version
+- description field contains the plugin description
+
+# After (consolidated)
+## Required Fields
+- name: Plugin name
+- version: Plugin version
+- description: Plugin description
+```
+
+**Command Optimization**:
+```markdown
+# Before (verbose)
+## What This Command Does
+
+This command will perform a comprehensive validation of your project's documentation against the Personal standards. It will check multiple aspects including README completeness, architecture diagrams, and ADRs.
+
+## Objective
+
+The objective of this command is to validate documentation.
+
+# After (optimized)
+## Objective
+
+Validate project documentation against standards (README, architecture diagrams, ADRs).
+```
+
+### Token Impact Estimation
+
+**Small optimization** (10-20 tokens):
+- Remove redundant headers
+- Consolidate similar sections
+- Shorten transition phrases
+
+**Medium optimization** (20-50 tokens):
+- Extract duplicated content to skills
+- Convert prose to lists/tables
+- Remove unnecessary examples
+
+**Large optimization** (50-100+ tokens):
+- Eliminate cross-file redundancy
+- Restructure verbose sections
+- Remove entire duplicate components
+
+### Optimization Tradeoff Considerations
+
+When evaluating whether to optimize, consider:
+
+**Benefits to assess**:
+- Token reduction (quantify: how many tokens saved?)
+- Cost savings (for frequently-used components)
+- Clarity improvement (does brevity improve focus?)
+- Maintenance efficiency (less to keep in sync)
+
+**Risks to assess**:
+- Context loss (is removed content genuinely redundant?)
+- Clarity reduction (does brevity create ambiguity?)
+- User expertise required (does optimization assume more knowledge?)
+- Refactoring effort (is the change worth the time?)
+
+**Decision criteria**:
+
+Optimize aggressively when:
+- Skills loaded frequently
+- Commands with >500 lines
+- Content with clear redundancy
+- Production-ready plugins
+
+Be conservative when:
+- Complex technical concepts
+- New user onboarding content
+- Safety-critical instructions
+- Prototype/experimental plugins

skills/marketplace-command-patterns.md

@@ -0,0 +1,309 @@
+---
+title: Marketplace Command Patterns
+description: Standard parameter patterns and output formatting for all marketplace commands
+tags: [commands, parameters, output, user-interface]
+---
+
+# Marketplace Command Patterns
+
+## Metadata
+
+**Purpose**: Define standard command patterns for consistent user experience across marketplace
+**Applies to**: All user-facing commands in marketplace plugins
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### Standard Output Parameters
+
+All user-facing commands in marketplace support:
+
+**Format Parameter:**
+- `--format=console` (default) - Display results in IDE/console
+- `--format=markdown` - Generate markdown report file
+
+**Output Parameter:**
+- `--output=<path>` - Specify custom report file path
+  - Only valid when `--format=markdown`
+  - If not specified, uses default report path
+
+**Default Report Paths:**
+- Pattern: `./reports/{command-name}-report.md`
+- Example: `./reports/validate-docs-report.md`
+
+### Parameter Documentation Template
+
+Include this section in every command file:
+
+```markdown
+## Command Parameters
+
+This command supports the following optional parameters:
+
+**Format Parameter:**
+- `--format=console` (default) - Display results in IDE/console
+- `--format=markdown` - Generate markdown report file
+
+**Output Parameter:**
+- `--output=<path>` - Specify custom report file path
+  - Default: `./reports/{command-name}-report.md`
+  - Only used with `--format=markdown`
+
+**Usage Examples:**
+\```bash
+/{plugin-name}:{command-name}                                    # Console output
+/{plugin-name}:{command-name} --format=markdown                  # Report in ./reports/
+/{plugin-name}:{command-name} --format=markdown --output=./docs/report.md
+\```
+```
+
+### Output Mode Implementation
+
+**When `--format=console` (default):**
+1. Display results directly in console/IDE
+2. Use clear formatting for readability
+3. Include summary statistics if applicable
+4. Provide actionable recommendations
+
+**When `--format=markdown`:**
+1. Check if user specified `--output` parameter
+   - If yes, use that path
+   - If no, use default: `./reports/{command-name}-report.md`
+2. Create report directory if it doesn't exist
+3. Generate properly formatted markdown file with:
+   - Metadata header (timestamp, project path, command used)
+   - Executive summary
+   - Detailed findings
+   - Recommendations
+   - Appendices (if applicable)
+4. After saving:
+   - Display confirmation with file path
+   - Show brief summary in console
+
+### Report File Structure
+
+All markdown reports should follow this structure:
+
+```markdown
+# {Command Name} Report
+
+**Generated**: {timestamp}
+**Project**: {project-path}
+**Command**: `/{plugin}:{command} {parameters}`
+
+---
+
+## Executive Summary
+
+[High-level overview of findings, 2-3 sentences]
+
+**Key Metrics**:
+- Metric 1: Value
+- Metric 2: Value
+
+---
+
+## Findings
+
+### {Category 1}
+[Detailed findings for category 1]
+
+### {Category 2}
+[Detailed findings for category 2]
+
+---
+
+## Recommendations
+
+**High Priority**:
+1. [Recommendation 1]
+2. [Recommendation 2]
+
+**Medium Priority**:
+1. [Recommendation 3]
+
+**Low Priority**:
+1. [Recommendation 4]
+
+---
+
+## Appendices
+
+### {Additional Details}
+[Supporting information, raw data, etc.]
+```
+
+### Parameter Parsing Pattern
+
+When implementing parameter handling in commands:
+
+```markdown
+## Parameter Detection
+
+1. Check for `--format` parameter:
+   - If `--format=markdown`, set output_mode to "markdown"
+   - Otherwise, set output_mode to "console" (default)
+
+2. Check for `--output` parameter (only if format=markdown):
+   - If specified, use that path for report file
+   - If not specified, use default: `./reports/{command-name}-report.md`
+   - If format=console, ignore --output parameter
+
+3. Validate parameters:
+   - Warn if `--output` used without `--format=markdown`
+   - Validate output path is writable
+```
+
+### Console Output Best Practices
+
+**Structure:**
+- Clear section headings
+- Use tables for metrics/scores
+- Use lists for findings/recommendations
+- Use visual separators (---, ===)
+
+**Tone:**
+- Actionable and specific
+- Avoid jargon where possible
+- Provide context for recommendations
+
+**Length:**
+- Concise but complete
+- Long details can go in markdown report
+
+### Markdown Report Best Practices
+
+**File Management:**
+- Always create parent directories if missing
+- Use consistent naming patterns
+- Timestamp reports for versioning
+- Overwrite existing report with same name (don't append)
+
+**Formatting:**
+- Use proper markdown hierarchy (# ## ###)
+- Include code blocks with language specifiers
+- Use tables for structured data
+- Use blockquotes for important notes
+
+**Content:**
+- Self-contained (don't assume reader has console output)
+- Include full context (project, command, timestamp)
+- Provide actionable recommendations
+- Link to relevant documentation/resources
+
+---
+
+## Resources
+
+### Complete Command Implementation Example
+
+```markdown
+---
+description: Validate documentation standards compliance
+---
+
+# Validate Documentation Command
+
+You are a documentation standards validator for Personal.
+
+## Command Parameters
+
+This command supports the following optional parameters:
+
+**Format Parameter:**
+- `--format=console` (default) - Display results in IDE/console
+- `--format=markdown` - Generate markdown report file
+
+**Output Parameter:**
+- `--output=<path>` - Specify custom report file path
+  - Default: `./reports/validate-docs-report.md`
+  - Only used with `--format=markdown`
+
+**Usage Examples:**
+\```bash
+/validator:validate-docs                                    # Console output
+/validator:validate-docs --format=markdown                  # Report in ./reports/
+/validator:validate-docs --format=markdown --output=./docs/validation.md
+\```
+
+## Output Mode Instructions
+
+### Step 1: Detect Output Mode
+
+Parse command parameters to determine output mode:
+- Check for `--format` parameter
+- Check for `--output` parameter (if format=markdown)
+- Set output_mode variable accordingly
+
+### Step 2: Perform Analysis
+
+[Execute validation logic here]
+
+### Step 3: Format Output
+
+**If output_mode is "console":**
+1. Display results directly in console
+2. Show summary, findings, recommendations
+3. Use clear formatting for readability
+
+**If output_mode is "markdown":**
+1. Determine output path:
+   - Use `--output` value if provided
+   - Otherwise use `./reports/validate-docs-report.md`
+2. Create report directory: `mkdir -p reports`
+3. Generate markdown report with proper structure
+4. Save to file using Write tool
+5. Confirm to user: "Report saved to {path}"
+6. Show brief summary in console
+
+## Validation Process
+
+1. Activate skill: `documentation-standards`
+2. Scan repository for documentation files
+3. Assess against standards
+4. Calculate scores
+5. Generate recommendations
+6. Format output based on output_mode
+
+## Output Format
+
+[Specific format for this command's findings]
+```
+
+### Parameter Handling Code Pattern
+
+When writing command instructions, include this pattern:
+
+```markdown
+## Parameter Handling
+
+**Step 1: Parse parameters from user command**
+
+Extract parameters from the command invocation:
+- `--format=console` or `--format=markdown`
+- `--output=<path>` (optional, only with markdown format)
+
+**Step 2: Set defaults**
+
+If no parameters specified:
+- `output_mode = "console"`
+- `output_path = null`
+
+If `--format=markdown` but no `--output`:
+- `output_path = "./reports/{command-name}-report.md"`
+
+**Step 3: Validate**
+
+- If `--output` specified without `--format=markdown`, warn user and ignore
+- Ensure output path is valid (if specified)
+
+**Step 4: Execute command**
+
+Proceed with command logic, keeping output_mode in mind
+
+**Step 5: Generate output**
+
+Format results according to output_mode (console or markdown)
+```

skills/marketplace-registration.md

@@ -0,0 +1,274 @@
+---
+title: Marketplace Registration Standards
+description: Plugin registration, versioning, tagging, and quality gates for marketplace
+tags: [registration, versioning, quality, marketplace]
+---
+
+# Marketplace Registration Standards
+
+## Metadata
+
+**Purpose**: Define registration process and quality standards for marketplace plugins
+**Applies to**: All Personal marketplace plugins
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### Marketplace Registration
+
+**marketplace.json Entry**:
+```json
+{
+  "name": "brads-marketplace",
+  "description": "Personal Custom Claude Plugins",
+  "owner": {
+    "name": "Personal Team"
+  },
+  "plugins": [
+    {
+      "name": "plugin-name",
+      "source": "./plugin-name",
+      "description": "Plugin description from plugin.json"
+    }
+  ]
+}
+```
+
+**Registration Process**:
+1. Create plugin in its own directory
+2. Add entry to root `marketplace.json`
+3. Description should match `plugin.json`
+4. Source is relative path from marketplace root
+
+### Documentation Standards
+
+**Plugin README** (if plugin is complex):
+- Purpose and use cases
+- Installation instructions
+- Command reference
+- Examples
+
+**Root CLAUDE.md** (marketplace-level):
+- Update with new plugin info
+- Add example commands
+- Note any cross-plugin workflows
+
+### Version Management
+
+**Semantic Versioning**:
+- `1.0.0` - Initial release
+- `1.1.0` - New commands/features (minor)
+- `1.0.1` - Bug fixes (patch)
+- `2.0.0` - Breaking changes (major)
+
+**What triggers major version**:
+- Removing commands
+- Changing command parameters (breaking)
+- Restructuring that affects users
+
+**What triggers minor version**:
+- Adding new commands
+- Adding new skills
+- Adding new agents
+- New features (non-breaking)
+
+**What triggers patch version**:
+- Bug fixes
+- Documentation updates
+- Performance improvements
+- Refactoring (no user-facing changes)
+
+### Quality Gates
+
+Before adding plugin to marketplace:
+- [ ] plugin.json with all required fields
+- [ ] All files have proper frontmatter
+- [ ] Commands follow output parameter standards
+- [ ] Purpose describable in 5-10 words
+- [ ] Entry added to marketplace.json
+- [ ] CLAUDE.md updated with examples
+- [ ] Tested with `claude plugins install ./plugin-name`
+
+**Additional quality checks**:
+- [ ] No duplicate knowledge across components
+- [ ] Skills use progressive disclosure (if applicable)
+- [ ] Component sizes within guidelines (agents <500, skills <400, commands <600 lines)
+- [ ] Clear separation of concerns (agent vs skill vs command)
+
+### Personal Tags
+
+Use these tags in plugin.json for discoverability:
+
+**Domain Tags**:
+- `standards` - Validation/compliance plugins
+- `investigation` - Analysis/discovery plugins
+- `development` - Dev tool plugins
+- `documentation` - Doc generation/validation
+
+**Function Tags**:
+- `validation` - Checks compliance
+- `analysis` - Analyzes code/architecture
+- `generation` - Creates artifacts
+- `orchestration` - Coordinates workflows
+
+**Context Tags**:
+- `labs` - Labs-specific
+- `python` - Python projects
+- `data-science` - ML/DS projects
+- `architecture` - System design
+
+**Technology Tags**:
+- `mlflow` - MLflow integration
+- `databricks` - Databricks integration
+- `spark` - Apache Spark
+- `pytest` - Testing with pytest
+- `poetry` - Poetry package management
+
+### Plugin Lifecycle
+
+**Development Phase**:
+- Version: `0.x.x`
+- Status: Experimental
+- Can make breaking changes frequently
+- Not recommended for production use
+
+**Stable Phase**:
+- Version: `1.x.x+`
+- Status: Stable
+- Follow semantic versioning strictly
+- Breaking changes only in major versions
+
+**Deprecated Phase**:
+- Mark in plugin.json: `"deprecated": true`
+- Document migration path in README
+- Provide timeline for removal
+- Suggest alternative plugins
+
+---
+
+## Resources
+
+### Complete marketplace.json Example
+
+```json
+{
+  "name": "brads-marketplace",
+  "description": "Personal Custom Claude Plugins",
+  "version": "1.0.0",
+  "owner": {
+    "name": "Personal Team",
+    "url": "https://github.com/USERNAME"
+  },
+  "plugins": [
+    {
+      "name": "validator",
+      "source": "./validator",
+      "description": "Standards validator for personal use projects",
+      "tags": ["standards", "validation", "personal"]
+    },
+    {
+      "name": "repo-investigator",
+      "source": "./repo-investigator",
+      "description": "Repository analysis and investigation tools",
+      "tags": ["investigation", "analysis", "personal"]
+    },
+    {
+      "name": "document-generator",
+      "source": "./document-generator",
+      "description": "Architecture documentation generation tools",
+      "tags": ["documentation", "generation", "personal"]
+    },
+    {
+      "name": "marketplace-dev",
+      "source": "./marketplace-dev",
+      "description": "Plugin development and architecture tools",
+      "tags": ["development", "architecture", "personal"]
+    }
+  ]
+}
+```
+
+### Plugin Release Checklist
+
+**Before 1.0.0 Release**:
+- [ ] All features implemented and tested
+- [ ] Documentation complete
+- [ ] Examples provided
+- [ ] Quality gates passed
+- [ ] Peer review completed
+- [ ] Breaking changes documented
+- [ ] Migration guide (if replacing existing plugin)
+
+**For Minor Version Release (1.x.0)**:
+- [ ] New features tested
+- [ ] Documentation updated
+- [ ] Backward compatibility verified
+- [ ] Examples updated
+- [ ] CHANGELOG.md updated
+
+**For Patch Version Release (1.0.x)**:
+- [ ] Bug fixes tested
+- [ ] No breaking changes
+- [ ] Documentation updated (if needed)
+- [ ] CHANGELOG.md updated
+
+### Deprecation Notice Template
+
+Add to plugin README.md:
+
+```markdown
+## ⚠️ Deprecation Notice
+
+This plugin is deprecated as of [date] and will be removed in [future date].
+
+**Reason**: [Why this plugin is being deprecated]
+
+**Migration Path**:
+- Use [alternative-plugin] instead
+- Migration guide: [link or instructions]
+- Support timeline: [when support ends]
+
+**Questions**: Contact Personal team
+```
+
+### Version History Template
+
+Add to plugin README.md or CHANGELOG.md:
+
+```markdown
+## Version History
+
+### v2.0.0 (2024-01-15)
+**Breaking Changes**:
+- Removed deprecated command `/old-command`
+- Changed parameter format for `/main-command`
+
+**New Features**:
+- Added `/new-command` for improved workflow
+- New skill: `advanced-analysis.md`
+
+**Migration Guide**:
+- Replace `/old-command` with `/new-command --mode=legacy`
+- Update parameter: `--old-param` → `--new-param`
+
+### v1.2.0 (2024-01-01)
+**New Features**:
+- Added support for Python 3.12
+- New skill: `python-312-features.md`
+
+**Bug Fixes**:
+- Fixed issue with virtual environment detection
+
+### v1.1.0 (2023-12-15)
+**New Features**:
+- Added `/quick-check` command
+- Performance improvements
+
+### v1.0.0 (2023-12-01)
+**Initial stable release**
+- Core validation features
+- Documentation generation
+- CLI integration
+```

skills/plugin-architecture-principles.md

@@ -0,0 +1,170 @@
+---
+title: Plugin Architecture Principles
+description: Core architectural principles for Personal marketplace plugins
+tags: [architecture, design-principles, best-practices]
+---
+
+# Plugin Architecture Principles
+
+## Metadata
+
+**Purpose**: Define core architectural principles for marketplace plugins
+**Applies to**: All plugin development
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### Core Philosophy
+
+Every plugin in the Personal marketplace follows these foundational principles:
+
+#### 1. Single Responsibility Principle
+- **Each plugin does ONE thing well**
+- Purpose must be describable in 5-10 words
+- If description needs "and" or "or", consider splitting
+- Average plugin size: 3-4 components
+
+**Examples**:
+- ✅ Good: "Validates documentation standards compliance"
+- ✅ Good: "Analyzes repository architecture and risks"
+- ❌ Too broad: "Validates everything and generates reports and fixes issues"
+
+#### 2. Composability Over Bundling
+- Prefer multiple focused plugins over one large plugin
+- Design components to work independently
+- Enable mix-and-match for custom workflows
+- Avoid tight coupling between unrelated features
+
+**Rationale**: Users can install only what they need, reducing cognitive load and token usage.
+
+#### 3. Progressive Disclosure
+- Load only what's needed when it's needed
+- Three-tier skill loading:
+  1. **Metadata** (always): Title, description, tags
+  2. **Instructions** (when activated): Core knowledge
+  3. **Resources** (on demand): Examples, reference materials
+- Commands should activate skills explicitly
+
+#### 4. Context Efficiency
+- Minimize token usage at every layer
+- Extract common knowledge to reusable skills
+- Avoid duplication across agents/commands
+- Optimize for fast, focused execution
+
+#### 5. Clear Boundaries
+- Agents provide reasoning and judgment
+- Skills provide knowledge and patterns
+- Commands provide orchestration and user interface
+- No overlap in responsibilities
+
+### Three-Layer Architecture
+
+**Layer 1: Agents** (`agents/`)
+- **What**: AI personas with domain expertise
+- **When**: Need reasoning, judgment, or contextual decision-making
+- **Size**: Typically 100-300 lines
+- **Contains**: Role definition, approach, decision-making framework
+
+**Layer 2: Skills** (`skills/`)
+- **What**: Modular knowledge packages
+- **When**: Reusable knowledge needed by multiple agents/commands
+- **Size**: Typically 50-200 lines (instructions section)
+- **Contains**: Standards, patterns, reference materials, methodologies
+
+**Layer 3: Commands** (`commands/`)
+- **What**: User-facing tools and workflows
+- **When**: Invokable actions with parameters and output
+- **Size**: Typically 100-400 lines (plus skill activation)
+- **Contains**: Parameter handling, workflow orchestration, output formatting
+
+### Design Decision Framework
+
+Use this framework to decide component structure:
+
+```
+START: What problem does this plugin solve?
+│
+├─ Is it a single, focused problem?
+│  ├─ YES → Good candidate for plugin
+│  └─ NO → Consider splitting into multiple plugins
+│
+├─ What expertise is needed?
+│  ├─ Domain reasoning → Create Agent
+│  └─ Just knowledge → Use Skill
+│
+├─ Is the knowledge reusable?
+│  ├─ YES → Create Skill
+│  └─ NO → Include in Command
+│
+└─ How do users invoke it?
+   ├─ Direct command → Create Command
+   └─ Background capability → Agent + Skills only
+```
+
+### Quality Metrics
+
+**Good Plugin Design**:
+- Purpose clear in 5-10 words ✅
+- 2-5 total components ✅
+- No knowledge duplication ✅
+- Works in isolation ✅
+- Composes with others ✅
+
+**Red Flags**:
+- Purpose requires long explanation ❌
+- 10+ component files ❌
+- Same knowledge in multiple files ❌
+- Requires other specific plugins ❌
+- Duplicate functionality ❌
+
+---
+
+## Resources
+
+### Anti-Patterns Reference
+
+Watch for these common mistakes during plugin design:
+
+**1. The Kitchen Sink**
+- **Problem**: Plugin tries to do everything
+- **Symptoms**: Purpose requires paragraph to explain, 10+ component files, "and/or" in description
+- **Fix**: Split into multiple focused plugins
+- **Example**: "Validates docs AND generates reports AND fixes code AND deploys" → Split into validator, document-generator, code-fixer, deployer plugins
+
+**2. The Encyclopedia**
+- **Problem**: Massive command files with all knowledge inline
+- **Symptoms**: Commands >600 lines, same documentation repeated across commands
+- **Fix**: Extract knowledge to reusable skills
+- **Example**: 800-line command with inline Python standards → Extract to `python-standards` skill, reference from command
+
+**3. The Duplicate**
+- **Problem**: Same information in agent, skills, and commands
+- **Symptoms**: Copy-pasted content, version drift between files, difficult updates
+- **Fix**: Single source of truth in skills, reference from agents/commands
+- **Example**: README template in 3 files → Create `readme-standards` skill, activate from commands
+
+**4. The Tangle**
+- **Problem**: Components with circular dependencies
+- **Symptoms**: Agent A needs Agent B which needs Agent A, skills that reference each other
+- **Fix**: Clear hierarchy: Commands → Agents → Skills (unidirectional flow)
+- **Example**: security-agent ← → compliance-agent → Create coordinator agent that uses both
+
+**5. The Orphan**
+- **Problem**: Component that doesn't fit plugin purpose
+- **Symptoms**: Component solves unrelated problem, rarely used with other components
+- **Fix**: Move to separate plugin or remove
+- **Example**: `format-code.md` command in a validation plugin → Move to code-formatter plugin
+
+**6. The Monolith Skill**
+- **Problem**: Single skill file with multiple unrelated domains
+- **Symptoms**: Skill >400 lines, contains 3+ distinct topics, commands only use 30% of content
+- **Fix**: Split into focused skills by domain
+- **Example**: `all-standards.md` (docs + testing + security) → Split into 3 skills
+
+**7. The Phantom Agent**
+- **Problem**: Agent that doesn't provide reasoning, just passes knowledge through
+- **Symptoms**: Agent has no decision-making logic, could be replaced with direct skill activation
+- **Fix**: Remove agent, have command directly activate skills
+- **Example**: Agent that only says "activate skill X" → Command activates skill X directly

skills/plugin-design-template.md

@@ -0,0 +1,251 @@
+---
+title: Plugin Design Document Template
+description: Standard template for documenting plugin architecture and implementation plans
+tags: [template, documentation, design, planning]
+---
+
+# Plugin Design Document Template
+
+## Metadata
+
+**Purpose**: Provide standard structure for plugin design documentation
+**Applies to**: All new plugin development in marketplace
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### When to Use This Template
+
+Use this template when:
+- Designing a new plugin from scratch
+- Documenting architecture decisions for a plugin
+- Planning refactoring of an existing plugin
+- Communicating plugin design to stakeholders
+
+### Template Sections
+
+The design document should include these sections in order:
+
+1. **Overview** - Purpose, use cases, scope
+2. **Architecture Decision** - Pattern and rationale
+3. **Component Design** - Detailed breakdown of agents, skills, commands
+4. **File Structure** - Directory layout
+5. **Token Budget Summary** - Estimated token usage
+6. **Implementation Checklist** - Step-by-step tasks
+7. **Next Steps** - Immediate actions to take
+
+---
+
+## Resources
+
+### Complete Design Document Template
+
+```markdown
+# Plugin Design: [Plugin Name]
+
+## Overview
+
+**Purpose**: [5-10 word description]
+**Use Cases**: [When users will invoke this]
+**Scope**: [What's included and excluded]
+
+## Architecture Decision
+
+**Pattern**: [Single-purpose / Workflow orchestration / Agent + Skill integration]
+
+**Rationale**: [Why this architecture fits the use case]
+
+## Component Design
+
+### Agents
+
+#### [Agent Name] (`agents/agent-name.md`)
+**Role**: [Expert persona and domain]
+**Responsibilities**:
+- [Responsibility 1]
+- [Responsibility 2]
+
+**Skills Used**:
+- `skill-name-1` - When [condition]
+- `skill-name-2` - When [condition]
+
+**Token Budget**: ~[X] tokens
+
+---
+
+### Skills
+
+#### [Skill Name] (`skills/skill-name.md`)
+**Purpose**: [What knowledge this provides]
+**Used By**: [Which agents/commands use this]
+
+**Tier 1: Metadata** (~75 tokens)
+- Title, description, tags
+
+**Tier 2: Instructions** (~[X] tokens)
+- [Core content outline]
+
+**Tier 3: Resources** (~[X] tokens)
+- [Detailed content outline]
+
+**Token Budget**: ~[X] tokens (Tier 1+2 typically loaded)
+
+---
+
+### Commands
+
+#### [Command Name] (`commands/command-name.md`)
+**Purpose**: [What user action this enables]
+**Parameters**:
+- Standard output parameters (--format, --output)
+- [Any custom parameters]
+
+**Workflow**:
+1. [Step 1]
+2. Activate agent: `agent-name`
+3. Agent activates skill: `skill-name`
+4. [Processing]
+5. Format output
+
+**Token Budget**: ~[X] tokens (command) + ~[Y] tokens (agent) + ~[Z] tokens (skills)
+**Total**: ~[X+Y+Z] tokens
+
+---
+
+## File Structure
+
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json
+├── agents/                   [if needed]
+│   └── agent-name.md
+├── skills/                   [if needed]
+│   ├── skill-name-1.md
+│   └── skill-name-2.md
+└── commands/
+    ├── command-1.md
+    └── command-2.md
+```
+
+## Token Budget Summary
+
+| Component | Typical Load | Max Load |
+|-----------|--------------|----------|
+| Agents | [X] tokens | [Y] tokens |
+| Skills | [X] tokens | [Y] tokens |
+| Commands | [X] tokens | [Y] tokens |
+| **Total** | **[X] tokens** | **[Y] tokens** |
+
+## Implementation Checklist
+
+- [ ] Create plugin directory structure
+- [ ] Write plugin.json
+- [ ] Implement agents (if applicable)
+- [ ] Implement skills with three-tier structure
+- [ ] Implement commands with output parameters
+- [ ] Add entry to marketplace.json
+- [ ] Update root CLAUDE.md
+- [ ] Test plugin installation
+- [ ] Test command invocation
+- [ ] Verify token usage
+
+## Next Steps
+
+1. **Create plugin structure**: `mkdir -p plugin-name/{.claude-plugin,agents,skills,commands}`
+2. **Write plugin.json**: Define metadata and tags
+3. **Implement components**: Start with commands, then agents, then skills
+4. **Test iteratively**: Install and test each component as built
+5. **Register in marketplace**: Add to marketplace.json when complete
+```
+
+### Token Budget Estimation Guidelines
+
+**Agents**:
+- Minimal agent (role + basic approach): ~200-300 tokens
+- Standard agent (role + detailed approach + skill activation): ~400-600 tokens
+- Complex agent (multiple personas + decision frameworks): ~600-800 tokens
+
+**Skills (Instructions tier)**:
+- Small skill (focused standards): ~300-500 tokens
+- Medium skill (comprehensive guide): ~600-1000 tokens
+- Large skill (reference material): ~1000-1500 tokens
+
+**Commands**:
+- Simple command (direct execution): ~200-400 tokens
+- Standard command (parameter handling + workflow): ~400-600 tokens
+- Complex command (multi-step orchestration): ~600-1000 tokens
+
+**Total Budget Targets**:
+- Simple plugin: 500-1500 tokens
+- Standard plugin: 1500-3000 tokens
+- Complex plugin: 3000-5000 tokens
+- Avoid exceeding 5000 tokens for typical use case
+
+### Architecture Pattern Examples
+
+**Single-Purpose Pattern**:
+```markdown
+## Architecture Decision
+
+**Pattern**: Single-Purpose Command
+
+**Rationale**: This plugin performs one focused task (format code files). It doesn't require expert reasoning or multiple knowledge domains, so a single command without agents/skills is sufficient.
+
+**Components**:
+- 1 command: `format-code.md`
+- 0 agents
+- 0 skills (logic is simple enough to include in command)
+```
+
+**Agent + Skills Pattern**:
+```markdown
+## Architecture Decision
+
+**Pattern**: Agent + Multiple Skills
+
+**Rationale**: This plugin requires expert judgment (security analysis) and references multiple knowledge domains (security standards, vulnerability patterns). An agent provides the expertise, while skills contain reusable security knowledge.
+
+**Components**:
+- 1 agent: `security-auditor.md`
+- 3 skills: `security-standards.md`, `vulnerability-patterns.md`, `remediation-guide.md`
+- 1 command: `audit-security.md`
+```
+
+**Workflow Orchestration Pattern**:
+```markdown
+## Architecture Decision
+
+**Pattern**: Workflow Orchestration
+
+**Rationale**: This plugin coordinates a multi-step workflow (setup project, configure CI/CD, generate docs). Multiple commands handle different aspects, sharing common skills for consistency.
+
+**Components**:
+- 0 agents (no expert reasoning needed)
+- 2 skills: `project-templates.md`, `configuration-standards.md`
+- 4 commands: `setup-structure.md`, `configure-ci.md`, `generate-docs.md`, `full-setup.md`
+```
+
+### Design Document Best Practices
+
+**Clarity**:
+- Use concrete examples, not abstract descriptions
+- Specify actual file names, not placeholders
+- Provide token estimates based on actual content planned
+
+**Completeness**:
+- Address all three layers (agents, skills, commands)
+- Explain rationale for architectural choices
+- Include both typical and maximum token budgets
+
+**Actionability**:
+- Implementation checklist should be specific
+- Next steps should be immediately actionable
+- File structure should be copy-paste ready
+
+**Realism**:
+- Don't over-architect simple plugins
+- Token budgets should be achievable
+- Component counts should match complexity

skills/plugin-structure-standards.md

@@ -0,0 +1,228 @@
+---
+title: Plugin Structure Standards
+description: File structure, naming conventions, and frontmatter requirements for marketplace plugins
+tags: [structure, naming, frontmatter, conventions]
+---
+
+# Plugin Structure Standards
+
+## Metadata
+
+**Purpose**: Define file structure and naming conventions for marketplace plugins
+**Applies to**: All Personal marketplace plugins
+**Version**: 1.0.0
+
+---
+
+## Instructions
+
+### Plugin Naming Conventions
+
+**Plugin Directory Names**:
+- Use kebab-case: `marketplace-dev`, `repo-investigator`
+- Be descriptive but concise
+- Avoid redundant "plugin" suffix
+
+**Plugin Names in plugin.json**:
+- Match directory name exactly
+- Used in marketplace.json registration
+- Used in command namespace (e.g., `/plugin-name:command`)
+
+### Required Files
+
+Every plugin MUST have:
+1. **`.claude-plugin/plugin.json`** - Plugin metadata
+2. **At least one**: Agent OR Command
+
+**plugin.json Structure**:
+```json
+{
+  "name": "plugin-name",
+  "description": "Clear 5-10 word description",
+  "version": "X.Y.Z",
+  "author": {
+    "name": "Personal Team"
+  },
+  "tags": ["relevant", "searchable", "tags"]
+}
+```
+
+### Directory Structure
+
+**Standard Layout**:
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json          # Required
+├── agents/                   # Optional
+│   └── expert-name.md
+├── skills/                   # Optional
+│   ├── knowledge-area-1.md
+│   └── knowledge-area-2.md
+└── commands/                 # Optional
+    ├── action-1.md
+    └── action-2.md
+```
+
+**Personal**:
+- All plugin development docs go in root `README.md`
+- No nested plugin directories
+- Flat structure within each component type
+
+### File Naming Conventions
+
+**Agents**: `{role}-{specialty}.md`
+- Examples: `plugin-architect.md`, `documentation-validator.md`
+- Lowercase, kebab-case
+- Descriptive of expertise
+
+**Skills**: `{domain}-{topic}.md`
+- Examples: `plugin-architecture-principles.md`, `progressive-disclosure.md`
+- Lowercase, kebab-case
+- Noun-focused
+
+**Commands**: `{action}-{target}.md`
+- Examples: `validate-docs.md`, `design-plugin.md`
+- Lowercase, kebab-case
+- Verb-focused
+
+### Frontmatter Requirements
+
+**All component files** must have YAML frontmatter:
+
+**Agents**:
+```yaml
+---
+description: Brief description of agent expertise
+---
+```
+
+**Skills**:
+```yaml
+---
+title: Skill Name
+description: One sentence description
+tags: [category, topic, use-case]
+---
+```
+
+**Commands**:
+```yaml
+---
+description: What this command does (one sentence)
+---
+```
+
+---
+
+## Resources
+
+### Complete Plugin Template
+
+```
+new-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── agents/
+│   └── domain-expert.md
+├── skills/
+│   ├── domain-knowledge.md
+│   └── methodology.md
+└── commands/
+    ├── quick-action.md
+    └── detailed-action.md
+```
+
+### plugin.json Template
+
+```json
+{
+  "name": "new-plugin",
+  "description": "Clear 5-10 word description of plugin purpose",
+  "version": "1.0.0",
+  "author": {
+    "name": "Personal Team"
+  },
+  "tags": [
+    "domain-tag",
+    "function-tag",
+    "personal"
+  ]
+}
+```
+
+### Agent File Template
+
+```markdown
+---
+description: Expert in [domain] for [purpose]
+---
+
+# [Agent Name] Agent
+
+You are a **[role description]** for Personal.
+
+Your expertise: [specific domain knowledge and approach]
+
+## Your Approach
+1. [Step 1]
+2. [Step 2]
+...
+
+## Skills Available
+- `skill-name-1` - Use when [condition]
+- `skill-name-2` - Use when [condition]
+```
+
+### Skill File Template
+
+```markdown
+---
+title: Skill Name
+description: One sentence description
+tags: [category, topic]
+---
+
+# Skill Name
+
+## Metadata
+**Purpose**: What this provides
+**Applies to**: When to use this
+**Version**: X.Y.Z
+
+---
+
+## Instructions
+[Core knowledge, always loaded when activated]
+
+---
+
+## Resources
+[Detailed examples, loaded on explicit request]
+```
+
+### Command File Template
+
+```markdown
+---
+description: What this command does
+---
+
+# Command Name
+
+You are a [role] performing [task].
+
+## Command Parameters
+[Reference `marketplace-command-patterns` skill for standard parameters]
+
+## Objective
+[What this command accomplishes]
+
+## Process
+1. [Step 1]
+2. Activate skill: `skill-name`
+3. [Step 3]
+
+## Output Format
+[How to structure the output]
+```

skills/progressive-disclosure.md

@@ -0,0 +1,270 @@
+---
+title: Progressive Disclosure Pattern
+description: Three-tier knowledge loading for efficient token usage
+tags: [skills, optimization, token-efficiency, loading-strategy]
+---
+
+# Progressive Disclosure Pattern
+
+## Metadata
+
+**Purpose**: Optimize token usage through progressive skill loading
+**Pattern**: Three-tier activation (metadata → instructions → resources)
+**Benefit**: Load only what's needed when it's needed
+
+---
+
+## Instructions
+
+### The Three-Tier Pattern
+
+Skills should be structured in three distinct sections that load progressively:
+
+#### Tier 1: Metadata (Always Loaded)
+**When**: Plugin loads, skill file scanned
+**Purpose**: Identification and discovery
+**Token Cost**: ~50-100 tokens
+**Contains**:
+- Title
+- Description (1-2 sentences)
+- Tags for categorization
+- Version/applicability info
+
+**Example**:
+```markdown
+---
+title: Python Packaging Standards
+description: Modern Python packaging best practices using pyproject.toml
+tags: [python, packaging, standards]
+---
+
+# Python Packaging Standards
+
+## Metadata
+**Purpose**: Guide Python package structure and configuration
+**Applies to**: All Python projects
+**Version**: 1.0.0
+```
+
+#### Tier 2: Instructions (Loaded When Activated)
+**When**: Agent/command explicitly activates the skill
+**Purpose**: Core knowledge and guidance
+**Token Cost**: ~500-1500 tokens
+**Contains**:
+- Core concepts and principles
+- Decision-making frameworks
+- Standards and best practices
+- Common patterns
+- Quick reference tables
+
+**Example**:
+```markdown
+## Instructions
+
+### Packaging Structure
+
+Modern Python projects use `pyproject.toml`:
+- Project metadata (name, version, description)
+- Dependencies (tool.poetry.dependencies)
+- Build system configuration
+- Tool-specific settings (pytest, mypy, ruff)
+
+### Best Practices
+1. Use `pyproject.toml` over `setup.py`
+2. Pin dependency versions for reproducibility
+3. Separate dev and production dependencies
+...
+```
+
+#### Tier 3: Resources (Loaded On Demand)
+**When**: Agent/command explicitly requests additional resources
+**Purpose**: Detailed examples, reference materials, edge cases
+**Token Cost**: ~1000-3000 tokens
+**Contains**:
+- Complete examples
+- Code templates
+- Detailed reference tables
+- Edge case handling
+- Troubleshooting guides
+
+**Example**:
+```markdown
+## Resources
+
+### Complete pyproject.toml Example
+\```toml
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "my-package"
+version = "0.1.0"
+...
+\```
+
+### Dependency Management Patterns
+...detailed examples...
+```
+
+### Activation Strategy
+
+**In Commands**:
+```markdown
+# Command starts
+## Analysis Process
+
+1. Determine project type
+2. **Activate skill**: `plugin-architecture-principles` (Tier 2)
+3. If detailed examples needed, load Tier 3 resources
+4. Apply knowledge to analysis
+```
+
+**In Agents**:
+```markdown
+# Agent definition
+You are a Python packaging expert.
+
+**Skills available**:
+- `python-packaging-standards` - Activate when analyzing Python projects
+- `dependency-management` - Activate when reviewing dependencies
+
+When encountering a Python project:
+1. Activate `python-packaging-standards` (Tier 2)
+2. Review structure against standards
+3. Request Tier 3 resources if edge cases encountered
+```
+
+### Token Optimization
+
+**Without Progressive Disclosure** (Always load everything):
+- Every invocation: ~3000 tokens of skill knowledge
+- 10 invocations: 30,000 tokens
+- Much knowledge never used
+
+**With Progressive Disclosure**:
+- Metadata (always): ~75 tokens
+- Instructions (when needed): +800 tokens
+- Resources (rarely): +2000 tokens
+- Average: ~875 tokens per invocation
+- 10 invocations: ~8,750 tokens (71% savings)
+
+### Design Guidelines
+
+**DO**:
+- ✅ Place essential guidance in Instructions
+- ✅ Move detailed examples to Resources
+- ✅ Keep Metadata concise (title, description, tags)
+- ✅ Make each tier independently valuable
+- ✅ Reference Resources from Instructions
+
+**DON'T**:
+- ❌ Put all knowledge in one section
+- ❌ Duplicate information across tiers
+- ❌ Load Resources by default
+- ❌ Hide essential info in Resources
+- ❌ Make tiers interdependent
+
+### Skill Size Targets
+
+| Tier | Target Size | Token Budget | Load Frequency |
+|------|------------|--------------|----------------|
+| Metadata | 50-100 lines | 75-150 tokens | Always |
+| Instructions | 100-300 lines | 500-1500 tokens | When activated |
+| Resources | 200-500 lines | 1000-3000 tokens | On explicit request |
+
+### When to Split Skills
+
+If a single skill exceeds these thresholds, consider splitting:
+
+**Too Large** (Instructions > 300 lines):
+```
+python-standards/  →  python-packaging-standards/
+                      python-testing-standards/
+                      python-code-quality/
+```
+
+**Too Granular** (Instructions < 50 lines):
+```
+ruff-setup/       →  python-code-quality/
+black-setup/          (combine related tools)
+mypy-setup/
+```
+
+---
+
+## Resources
+
+### Complete Skill Template
+
+```markdown
+---
+title: [Skill Name]
+description: [One sentence description]
+tags: [category, topic, use-case]
+---
+
+# [Skill Name]
+
+## Metadata
+
+**Purpose**: [What this skill provides]
+**Applies to**: [When to use this skill]
+**Version**: [Skill version]
+
+---
+
+## Instructions
+
+### [Core Concept 1]
+[Essential knowledge that's always needed when skill is activated]
+
+### [Core Concept 2]
+[More essential knowledge]
+
+### [Quick Reference]
+[Tables, lists, decision frameworks]
+
+**Note**: For detailed examples, see Resources section below.
+
+---
+
+## Resources
+
+### [Detailed Example 1]
+[Complete code examples, templates]
+
+### [Edge Case Handling]
+[Unusual situations, troubleshooting]
+
+### [Reference Materials]
+[Comprehensive tables, detailed guides]
+```
+
+### Real-World Example: Documentation Standards
+
+**Metadata** (~75 tokens, always loaded):
+```markdown
+---
+title: Personal Documentation Standards
+description: Required documentation for personal use project maturity tiers
+tags: [documentation, standards, maturity-tiers]
+---
+```
+
+**Instructions** (~1000 tokens, loaded when validating docs):
+- Tier definitions (Prototype/MVP/Production)
+- Required doc types (README, ADRs, diagrams)
+- Scoring methodology
+- Validation checklist
+
+**Resources** (~2500 tokens, loaded only if needed):
+- Complete scoring examples
+- Full README template
+- Detailed ADR format
+- Comprehensive diagram examples
+
+**Usage**:
+- Most validations: Metadata + Instructions (~1075 tokens)
+- Creating templates: All tiers (~3575 tokens)
+- Simple checks: Metadata only (~75 tokens)