terrylica/cc-skills

plugin-validator

Validate plugin structure and silent failures.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/terrylica/cc-skills --skill plugin-validator

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Plugin Validator

Comprehensive validation for Claude Code marketplace plugins.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

  • Validating plugin structure before release
  • Auditing hooks for silent failures
  • Checking plugin.json syntax and required fields
  • Verifying skill file formatting and frontmatter

Quick Start

bash
# Validate a specific plugin
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/

# Validate with fix suggestions
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/ --fix

Validation Phases

Phase 1: Structure Validation

Check plugin directory structure:

bash
/usr/bin/env bash << 'VALIDATE_EOF'
PLUGIN_PATH="${1:-.}"

# Check plugin.json exists
if [[ ! -f "$PLUGIN_PATH/plugin.json" ]]; then
    echo "ERROR: Missing plugin.json" >&2
    exit 1
fi

# Validate JSON syntax
if ! jq empty "$PLUGIN_PATH/plugin.json" 2>/dev/null; then
    echo "ERROR: Invalid JSON in plugin.json" >&2
    exit 1
fi

# Check required fields
REQUIRED_FIELDS=("name" "version" "description")
for field in "${REQUIRED_FIELDS[@]}"; do
    if ! jq -e ".$field" "$PLUGIN_PATH/plugin.json" >/dev/null 2>&1; then
        echo "ERROR: Missing required field: $field" >&2
        exit 1
    fi
done

echo "Structure validation passed"
VALIDATE_EOF

Phase 2: Silent Failure Audit

Critical Rule: All hook entry points MUST emit to stderr on failure.

Run the audit script:

bash
uv run plugins/plugin-dev/skills/plugin-validator/scripts/audit_silent_failures.py plugins/my-plugin/

What Gets Checked

CheckTarget FilesPattern
Shellcheckhooks/*.shSC2155, SC2086, etc.
Silent bashhooks/*.sh`mkdir\cp\mv\rm\jq without if !`
Silent Pythonhooks/*.pyexcept.*: pass without stderr

Hook Entry Points vs Utility Scripts

LocationTypeRequirement
plugins/*/hooks/*.shEntry pointMUST emit to stderr
plugins/*/hooks/*.pyEntry pointMUST emit to stderr
plugins/*/scripts/*.shUtilityFallback behavior OK
plugins/*/scripts/*.pyUtilityFallback behavior OK

Phase 3: Fix Patterns

Bash: Silent mkdir

bash
# BAD - silent failure
mkdir -p "$DIR"

# GOOD - emits to stderr
if ! mkdir -p "$DIR" 2>&1; then
    echo "[plugin] Failed to create directory: $DIR" >&2
fi

Python: Silent except pass

python
# BAD - silent failure
except (json.JSONDecodeError, OSError):
    pass

# GOOD - emits to stderr
except (json.JSONDecodeError, OSError) as e:
    print(f"[plugin] Warning: {e}", file=sys.stderr)

Integration with /plugin-dev:create

This skill is invoked in Phase 3 of the plugin-add workflow:

markdown
### 3.4 Plugin Validation

**MANDATORY**: Run plugin-validator before registration.

Task with subagent_type="plugin-dev:plugin-validator"
prompt: "Validate the plugin at plugins/$PLUGIN_NAME/"

Exit Codes

CodeMeaning
0All validations passed
1Violations found (see output)
2Error (invalid path, missing files)

References

Troubleshooting

IssueCauseSolution
plugin.json not foundMissing manifest fileCreate plugin.json with required fields
Invalid JSON syntaxMalformed plugin.jsonRun jq empty plugin.json to find syntax errors
Missing required fieldIncomplete manifestAdd name, version, description to plugin.json
Shellcheck errorsBash script issuesRun shellcheck hooks/*.sh to see details
Silent failure in bashMissing error handlingAdd if ! check around mkdir/cp/mv/rm commands
Silent except:pass in PythonMissing stderr outputAdd print(..., file=sys.stderr) before pass
Exit code 2Invalid path or missing filesVerify plugin path exists and has correct structure
Violations after --fixFix suggestions not appliedManually apply suggested fixes from output

Post-Execution Reflection

After this skill completes, reflect before closing the task:

  1. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
  2. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
  3. What worked better than expected? — Promote it to recommended practice. Document why.
  4. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
  5. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.



同じリポジトリから

関連する Skills

すべての Skills
terrylica
コミュニティ

academic-pdf-to-gfm

Convert academic PDF papers to GitHub-renderable GFM markdown with math equations. TRIGGERS - PDF, GitHub markdown, math

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

adr-code-traceability

Add ADR references to code for traceability. TRIGGERS - ADR traceability, code reference, document decision in code.

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

arxiv-source-first-paper-ingest

Read an arXiv paper faithfully by fetching the authors' own LaTeX source instead of OCR-ing the PDF. Extracts every display equation with its label, environment and enclosing proposition, renders each to MathML, and proves usability by compiling each formula with a real TeX engine. Use when you need a paper's formulas exactly — to replicate a method, implement a loss function or custom objective, verify a quoted number, or check a claim against what the authors actually wrote. TRIGGERS - read th

1時間の導入数
1
GitHub Stars
2
更新日
11月5日
terrylica
コミュニティ

azure-provision

Bootstrap Azure automation when interactive az login is blocked by a Conditional Access policy (error 530035, "Device state: Unregistered"). Mints a service principal through the Azure Portal session ONCE — using Microsoft Graph over a captured token, not DOM clicking — then provisions resource groups, Cognitive Services / AI Language / Speech resources and their keys entirely via az/REST, writing key AND endpoint together into the SCS vault. Use when az login fails but the portal works, when mo

1時間の導入数
1
GitHub Stars
2
更新日
11月5日