# Opencode Skills Maintainer

> Scan, validate, and audit OpenCode skills for consistency, redundancy, and modularization opportunities Use when this capability is needed.

- Skill: `tomevault-io/opencode-skills-maintainer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/opencode-skills-maintainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/opencode-skills-maintainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/opencode-skills-maintainer

---


## What I do

I maintain skill consistency, quality, and efficiency by:

1. **Discover All Skills**: Scan the `skills/` folder to discover all available skills
2. **Extract Skill Metadata**: Read frontmatter from each SKILL.md file (name, description, category)
3. **Validate Skill Structure**: Ensure all skills have required fields and valid frontmatter
4. **Categorize Skills**: Organize skills into logical categories (Framework, Test Generators, Linters, etc.)
5. **Detect Redundancy**: Identify overlapping functionality, duplicate capabilities, and consolidation opportunities
6. **Analyze Modularization**: Recommend skill decomposition and reusable component extraction
7. **Generate Report**: Provide comprehensive summary with validation status and optimization recommendations

## When to use me

Use this skill when:
- You want to audit all skills in the repository
- You need to validate skill metadata consistency
- You're checking for missing required fields in SKILL.md files
- You want a categorized list of all available skills
- You're debugging skill discovery issues
- You need to identify redundant functionality across multiple skills
- You're planning to refactor or consolidate the skill library
- You want to improve maintainability and reduce code duplication in skills

## Prerequisites

- Access to the repository root directory
- `jq` tool installed for JSON validation
- Python 3+ installed for YAML parsing

## Steps

### Step 1: Discover All Skills

Scan the `skills/` folder to find all skill directories:

```bash
# Find all skill directories
find skills/ -name "SKILL.md" -type f | sort
```

### Step 2: Extract Skill Metadata

For each skill, read the frontmatter to extract:

```bash
# Extract name and description from frontmatter
for skill_dir in skills/*/; do
  echo "=== $(basename "$skill_dir") ==="
  head -10 "$skill_dir/SKILL.md" | grep -E "(name:|description:)" | head -2
  echo
done
```

**Required Fields**:
- `name`: The skill identifier
- `description`: Brief description of what the skill does
- Optional: `category`, `workflow`, `audience` (from metadata section)

### Step 3: Validate Skill Structure

Check all skills for required fields and valid frontmatter:

```bash
# Validate all SKILL.md files
for dir in skills/*/; do
  skill_name=$(basename "$dir")
  echo "Validating: $skill_name"
  
  # Check for required fields
  if ! grep -q "^name:" "$dir/SKILL.md"; then
    echo "  ❌ Missing 'name:' field"
  else
    echo "  ✓ Has 'name:' field"
  fi
  
  if ! grep -q "^description:" "$dir/SKILL.md"; then
    echo "  ❌ Missing 'description:' field"
  else
    echo "  ✓ Has 'description:' field"
  fi
  
  # Validate YAML syntax (requires python3 and pyyaml)
  if python3 -c "import yaml; yaml.safe_load(open('$dir/SKILL.md'))" 2>&1; then
    echo "  ✓ Valid YAML frontmatter"
  else
    echo "  ❌ Invalid YAML frontmatter"
  fi
done
```

### Step 4: Categorize Skills

Organize skills into logical categories based on naming patterns:

| Category | Pattern | Examples |
|----------|---------|----------|
| Framework | `*-framework`, `*-workflow` | linting-workflow, test-generator-framework |
| Git/Workflow | `git-*`, `jira-*`, `pr-*`, `ticket-*` | git-issue-plan-workflow, jira-git-integration |
| OpenTofu/IaC | `opentofu-*` | opentofu-aws-explorer, opentofu-kubernetes-explorer |
| OpenCode Meta | `opencode-*` | opencode-agent-creation, opencode-skill-creation |
| Language-Specific | `{lang}-*`, `{framework}-*` | python-pytest-creator, nextjs-unit-test-creator |
| Code Quality | `*-linter`, `*-principle`, `*-generator` | python-ruff-linter, docstring-generator |
| Utilities | Other single-purpose | ascii-diagram-creator, tdd-workflow |

**Categorization Rule**: Match skill name against patterns above. First match wins.

### Step 5: Detect Redundancy & Modularization

Analyze skills for overlap and optimization opportunities:

**Redundancy Detection**:
- Compare skill descriptions for overlapping functionality
- Identify similar capability patterns across skills
- Flag skills with near-identical purposes or audiences
- Map skill interdependencies and coupling relationships

**Granularity Assessment**:
- Evaluate whether skills can be broken down into smaller, reusable components
- Identify compound skills that contain multiple distinct capabilities
- Assess potential for extracting shared functionality into base skills

**Analysis Commands**:
```bash
# Find skills with similar descriptions
grep -h "^description:" skills/*/SKILL.md | sort | uniq -c | sort -nr

# Analyze skill distribution by workflow type
grep -A1 "workflow:" skills/*/SKILL.md | grep "workflow:" | sort | uniq -c

# Check for naming convention compliance
ls skills/ | grep -E "^[a-z0-9]+(-[a-z0-9]+)*$"
```

**Modularization Opportunities**:
- Compound skills that can be broken into smaller components
- Shared functionality that could be extracted into base skills
- Skills that reference or build upon other skills
- Consolidation candidates with migration paths

### Step 6: Generate Report

Create a summary of all skills:

```markdown
# Skills Maintenance Report

## Skills Found: {total_count}

### Validation Summary
- ✓ Valid skills: {count}
- ❌ Invalid skills: {count}
- ⚠️ Missing optional fields: {count}

### Categories
- Framework Skills: {count}
- Language-Specific Test Generators: {count}
- Language-Specific Linters: {count}
- Project Setup: {count}
- Git/Workflow: {count}
- OpenCode Meta: {count}
- OpenTofu/Infrastructure: {count}
- Code Quality/Documentation: {count}
- Utilities: {count}

### Issues Found (if any)
- [skill-name]: Missing required field 'description'
- [skill-name]: Invalid YAML frontmatter

## Validation
✓ All required fields present
✓ All YAML frontmatter valid
✓ All skills categorized correctly
```

## Best Practices

### Categorization Logic

- **Framework**: Foundational workflows (`*-framework`, `*-workflow`)
- **Language-Specific**: Skills for specific languages/frameworks (`{lang}-*`, `{framework}-*`)
- **Meta**: Skills that create/audit other skills or agents (`opencode-*`)
- **Domain-Specific**: Skills for specific domains (`opentofu-*`, `git-*`, `jira-*`)

### Validation Rules

1. **Required Fields**: Every SKILL.md must have `name` and `description` in frontmatter
2. **YAML Syntax**: Frontmatter must be valid YAML
3. **File Naming**: Skill directory name should match the skill name (lowercase, hyphens)
4. **Description Length**: Keep descriptions between 50-150 characters

## Common Issues

### SKILL.md Not Found

**Issue**: Cannot find SKILL.md in a skill directory

**Solution**:
```bash
# Verify SKILL.md exists for all skills
for dir in skills/*/; do
  if [ ! -f "$dir/SKILL.md" ]; then
    echo "Missing SKILL.md in: $dir"
  fi
done
```

### Invalid Frontmatter

**Issue**: SKILL.md has missing or malformed frontmatter

**Solution**:
```bash
# Check for required frontmatter fields
for dir in skills/*/; do
  if ! grep -q "^name:" "$dir/SKILL.md"; then
    echo "Missing 'name:' field in: $dir/SKILL.md"
  fi
  if ! grep -q "^description:" "$dir/SKILL.md"; then
    echo "Missing 'description:' field in: $dir/SKILL.md"
  fi
done
```

### YAML Parse Errors

**Issue**: Python YAML parser fails on SKILL.md

**Solution**:
- Check for unclosed quotes in frontmatter
- Ensure proper indentation
- Verify no trailing spaces in YAML keys
- Check for special characters that need escaping

## Verification Commands

After running this skill, verify with these commands:

```bash
# Count total skills
find skills/ -name "SKILL.md" -type f | wc -l

# List all skill names
for dir in skills/*/; do
  grep "^name:" "$dir/SKILL.md" | head -1
done | sort

# Validate all YAML frontmatter
for dir in skills/*/; do
  python3 -c "import yaml; yaml.safe_load(open('$dir/SKILL.md'))" 2>&1 && echo "✓ $(basename $dir)"
done
```

**Verification Checklist**:
- [ ] All skill directories have SKILL.md files
- [ ] All SKILL.md files have valid YAML frontmatter
- [ ] All skills have required `name` field
- [ ] All skills have required `description` field
- [ ] Skill names match directory names
- [ ] All skills are categorized correctly
- [ ] Descriptions are concise and accurate

## Example Output

**Skills Found: 46**

### Validation Summary
- ✓ Valid skills: 46
- ❌ Invalid skills: 0
- ⚠️ Missing optional fields: 2

### Categories
- Framework Skills: 7
- Git/Workflow: 12
- OpenTofu/IaC: 7
- OpenCode Meta: 3
- Language-Specific: 6
- Code Quality: 8
- Utilities: 3

### Skills Missing Optional Fields
- ascii-diagram-creator: Missing 'workflow' metadata
- tdd-workflow: Missing 'audience' metadata

## Validation
✓ All required fields present
✓ All YAML frontmatter valid
✓ All skills categorized correctly

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/darellchua2) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->