JinDaGe - opencode-skills-maintainer Skill Details

What I do

I maintain the Build-With-Skills and Plan-With-Skills agents by:

Discover All Skills: Scan the skills/ folder to discover all available skills
Extract Skill Metadata: Read frontmatter from each SKILL.md file (name, description, category)
Categorize Skills: Organize skills into logical categories (Framework, Test Generators, Linters, etc.)
Update Agent Prompts: Update both Build-With-Skills and Plan-With-Skills system prompts with the complete, current skill list
Validate Changes: Ensure config.json is valid after updates
Generate Report: Provide a summary of changes made

When to use me

Use this skill when:

You've added new skills to the skills/ folder
You've removed skills from the skills/ folder
You've updated skill descriptions or metadata
You want to ensure agents have the latest skill list
Agents are unable to find skills that should be available

Prerequisites

Access to the repository root directory
jq tool installed for JSON validation
Python 3+ installed for JSON manipulation
Write permissions for config.json

Steps

Step 1: Discover All Skills

Scan the skills/ folder to find all skill directories:

# 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:

# 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 (used in agent prompts)
description: Brief description of what the skill does
Optional: category, workflow, audience (from metadata section)

Step 3: Categorize Skills

Organize skills into logical categories:

# Framework Skills (Foundational Workflows)
- linting-workflow
- test-generator-framework
- ticket-branch-workflow
- pr-creation-workflow

# Language-Specific Test Generators
- python-pytest-creator
- nextjs-unit-test-creator

# Language-Specific Linters
- python-ruff-linter
- javascript-eslint-linter

# Project Setup
- nextjs-standard-setup

# Git/Workflow
- git-issue-creator
- git-pr-creator
- jira-git-integration
- jira-git-workflow
- nextjs-pr-workflow

# OpenCode Meta
- opencode-agent-creation
- opencode-skill-creation
- opencode-skill-auditor

# OpenTofu/Infrastructure
- opentofu-provider-setup
- opentofu-provisioning-workflow
- opentofu-aws-explorer
- opentofu-kubernetes-explorer
- opentofu-neon-explorer
- opentofu-keycloak-explorer

# Code Quality/Documentation
- docstring-generator
- typescript-dry-principle
- coverage-readme-workflow

# Utilities
- ascii-diagram-creator

Step 4: Update Build-With-Skills Agent Prompt

Generate the "Available Skills" section for Build-With-Skills:

# Python script to update Build-With-Skills prompt
import json

# Build the skills section
skills_section = """## Available Skills (Hardcoded in System Prompt)

### Framework Skills (Foundational Workflows)
- **linting-workflow**: {description}
- **test-generator-framework**: {description}
- **ticket-branch-workflow**: {description}
- **pr-creation-workflow**: {description}

### Language-Specific Test Generators
- **python-pytest-creator**: {description}
- **nextjs-unit-test-creator**: {description}

# ... (continue for all categories)

"""

Update Process:

Read current config.json
Replace the skill discovery section with hardcoded skill list
Remove references to SKILL_INDEX.json
Update skill execution paths from [skill-path] to [skill-name]
Preserve all other prompt content (workflow, guidelines, QA)
Write back to config.json

Step 5: Update Plan-With-Skills Agent Prompt

Generate the same "Available Skills" section for Plan-With-Skills:

The skills section should be identical between both agents to ensure consistency.

Update Process:

Read current config.json
Replace the skill discovery section with hardcoded skill list
Remove references to SKILL_INDEX.json
Update skill selection guidelines to match hardcoded list
Preserve all other prompt content (workflow, guidelines, QA)
Write back to config.json

Step 6: Validate Changes

Validate the updated config.json:

# Validate JSON syntax
jq . config.json

# Check if JSON is valid
echo "Exit code: $?"
# Exit code 0 = valid JSON

Step 7: Generate Report

Create a summary of changes:

# Skills Maintenance Report

## Skills Found: {total_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}

## Changes Made
- Updated Build-With-Skills agent prompt with {count} skills
- Updated Plan-With-Skills agent prompt with {count} skills
- Removed SKILL_INDEX.json references
- Updated skill discovery workflow to use hardcoded list

## New Skills Added (if any)
- [skill-name]: description

## Removed Skills (if any)
- [skill-name]: previously in list

## Validation
✓ JSON validation passed
✓ Both agents updated successfully
✓ Skill lists synchronized

Best Practices

Categorization Logic

Framework Skills: Skills that provide foundational workflows used by other skills

Test framework, linting framework, PR workflow, ticket workflow

Language-Specific: Skills for specific programming languages or frameworks

Test generators, linters, project setup

Meta Skills: Skills that create/audit other skills or agents

opencode-agent-creation, opencode-skill-creation, opencode-skill-auditor

Domain-Specific: Skills for specific domains

OpenTofu infrastructure, Git/DevOps, documentation

Prompt Structure

Both agent prompts should follow this structure:

Available Skills (hardcoded, categorized)
Core Workflow (updated to remove SKILL_INDEX.json)
Skill Selection Guidelines (match hardcoded list)
Skill Execution Process (path updated to [skill-name])
Error Handling (no fallback to SKILL_INDEX.json)
Quality Assurance (unchanged)
Output Format (no first step to read SKILL_INDEX.json)

Consistency

Both agents should have identical skill lists and categories
Skill names and descriptions should match SKILL.md exactly
Maintain alphabetical ordering within categories
Use consistent formatting (bold names, descriptions after colon)

Common Issues

SKILL.md Not Found

Issue: Cannot find SKILL.md in a skill directory

Solution:

# 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:

# 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

JSON Validation Fails

Issue: jq . config.json returns errors

Solution:

Check for unclosed brackets or quotes
Ensure strings are properly escaped
Verify no trailing commas in JSON arrays

Use Python JSON validation as backup:

python3 -m json.tool config.json > /dev/null

Agent Prompts Not Updated

Issue: config.json changes don't reflect in agent prompts

Solution:

Verify config.json was saved correctly
Check that Python script wrote the file successfully
Re-run this skill to regenerate prompts
Manually verify prompt sections with jq

Verification Commands

After running this skill, verify with these commands:

# Verify JSON syntax
jq . config.json && echo "✓ JSON valid"

# Check Build-With-Skills has skill list
jq '.agent["build-with-skills"].prompt' config.json | grep "Available Skills" && echo "✓ Build-With-Skills updated"

# Check Plan-With-Skills has skill list
jq '.agent["plan-with-skills"].prompt' config.json | grep "Available Skills" && echo "✓ Plan-With-Skills updated"

# Verify no SKILL_INDEX.json references
! jq '.agent["build-with-skills"].prompt' config.json | grep -q "SKILL_INDEX.json" && echo "✓ SKILL_INDEX.json references removed"

# Verify both agents have identical skill sections
BWS_SKILLS=$(jq '.agent["build-with-skills"].prompt' config.json | sed -n '/## Available Skills/,/## Core Workflow/p')
PWS_SKILLS=$(jq '.agent["plan-with-skills"].prompt' config.json | sed -n '/## Available Skills/,/## Core Workflow/p')
[ "$BWS_SKILLS" = "$PWS_SKILLS" ] && echo "✓ Skill lists synchronized"

Verification Checklist:

[ ] JSON validation passes
[ ] Build-With-Skills has "Available Skills" section
[ ] Plan-With-Skills has "Available Skills" section
[ ] Both skill lists are identical
[ ] No SKILL_INDEX.json references remain
[ ] Skill names match SKILL.md files
[ ] All skills are categorized correctly
[ ] Descriptions match SKILL.md frontmatter

Automation

This skill can be automated with a cron job or git hook:

Git Pre-Commit Hook:

#!/bin/bash
# .git/hooks/pre-commit

# Check if skills changed
if git diff --name-only --cached | grep -q "^skills/"; then
  echo "Skills changed, updating agent prompts..."
  opencode --agent build-with-skills "Use opencode-skills-maintainer to update agent prompts"
fi

Cron Job (run daily):

# Run at 2 AM daily
0 2 * * * cd /path/to/repo && opencode --agent build-with-skills "Use opencode-skills-maintainer to update agent prompts"

Example Output

Skills Found: 27

Changes Made

Updated Build-With-Skills agent prompt with 27 skills
Updated Plan-With-Skills agent prompt with 27 skills
Removed SKILL_INDEX.json references
Updated skill discovery workflow to use hardcoded list

New Skills Added

nextjs-standard-setup: Create standardized Next.js 16 demo applications with shadcn, Tailwind v4, and specific folder structure using Tekk-prefixed components

Validation

✓ JSON validation passed ✓ Both agents updated successfully ✓ Skill lists synchronized

Related Skills

opencode-agent-creation: For creating new agents
opencode-skill-creation: For creating new skills
opencode-skill-auditor: For auditing skill redundancy