К основному содержанию
скилл CX Codex

skill-perfection — скилл для Claude Code: что делает и как установить

Скилл skill-perfection проводит аудит и сразу исправляет файлы скиллов по официальной документации. Пригодится перед публикацией или релизом плагина.

MIT ★ 125 обновлён 2026-06-23

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add OmidZamani/dspy-skills --skill skill-perfection -a claude-code
Открыть на GitHub

Что делает skill-perfection

Скилл выстраивает сквозную проверку файлов инструкций за один проход: если агент находит ошибку, он тут же правит файл и продолжает дальше. Процесс исключает повторные циклы согласования. В ходе работы сверяются вызовы API и доступность ссылок через веб-поиск.

В состав входит скрипт scripts/preflight.py, который запускается через uv run python для черновой проверки синтаксиса в Python-блоках. Скрипт чисто рекомендательный: если в скилле код на TypeScript или Go, либо утилита выдаёт неясные ошибки, этот шаг сразу пропускают, а аудит целиком доверяют модели.

Завершив правки, ассистент точечно перепроверяет три-пять исправлений и генерирует отчёт PERFECTION_REPORT.md размером до ста строк со списком замен и ссылками на источники. Без установленного uv предварительный скрипт запустить не получится, поэтому текстовый разбор остаётся главным инструментом.

Какие задачи решает

  • Сверить сигнатуры вызовов API и пути импортов с официальной документацией
  • Исправить ошибки синтаксиса в блоках кода прямо в файле скилла
  • Найти и обновить неработающие внешние ссылки
  • Сформировать итоговый отчёт PERFECTION_REPORT.md с историей правок

Примеры запросов агенту

  • Проверь и исправь файл skill.md по документации с помощью skill-perfection
  • Сделай QA-аудит скилла skills/my-agent/SKILL.md и сохрани отчёт

Как установить skill-perfection

1Через Skills CLI (Vercel)

npx skills add OmidZamani/dspy-skills --skill skill-perfection -a claude-code

2Вручную: положить файлы

~/.claude/skills/skills-skill-perfection/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/skills-skill-perfection/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о skill-perfection

Как установить skill-perfection в Claude Code?

Выполните в терминале команду npx skills add OmidZamani/dspy-skills --skill skills-skill-perfection -a claude-code. Файл сохранится по пути ~/.claude/skills/skills-skill-perfection/SKILL.md.

Что делает скилл skill-perfection?

Он проверяет markdown-файлы инструкций, сверяет вызовы библиотек с официальной документацией, на месте исправляет ошибки и создаёт отчёт.

Обязательно ли запускать скрипт preflight.py?

Нет, этот скрипт носит рекомендательный характер и проверяет синтаксис только в блоках на Python. Для других языков или при сбоях утилиты этот этап пропускают.

Исходный текст

SKILL.md · MIT
---
name: skill-perfection
description: "Use this skill when you need to QA audit and fix a plugin skill file. Provides a methodology for verifying skill content against official documentation, fixing issues in-place, and producing verification reports."
version: 1.1.0
---

# Skill Perfection

A systematic process for auditing and fixing plugin skills in a single pass.

## Core Principle

**Audit + Fix in One Pass**: When you find an issue, fix it immediately, then continue. This eliminates redundant research and multiple iterations.

## Process Overview

```
[Optional Preflight] → Audit+Fix (single pass) → Verify (spot-check) → Report
```

## Phase 1: Preflight (Optional, Advisory)

A Python-based preflight script is bundled for **Python-heavy skills only**. 

### When to Use Preflight

| Skill Content | Use Preflight? |
|---------------|----------------|
| Mostly Python code blocks | ✅ Yes |
| Mixed Python + other languages | ⚠️ Optional (Python blocks only) |
| Non-Python (JS, Rust, Go, etc.) | ❌ Skip, go to Phase 2 |
| Skill about the preflight script itself | ❌ Skip (conflict of interest) |

### Running Preflight

```bash
uv run python ${SKILL_DIR}/scripts/preflight.py <path-to-skill.md> --no-urls
```

### Interpreting Results

| Result | Action |
|--------|--------|
| `✅ PASSED` | Good signal. Proceed to Phase 2, trust syntax is valid. |
| `❌ FAILED` with clear errors (syntax error at line X) | Fix those specific issues, then proceed to Phase 2. |
| `❌ FAILED` with confusing/many errors | **Ignore preflight entirely.** Proceed to Phase 2, let LLM verify. |
| Script crashes or hangs | **Ignore preflight entirely.** Proceed to Phase 2. |

### Key Rule: Preflight is Advisory

**The preflight script is a helper, not a gatekeeper.** If it produces confusing output, skip it. The LLM-based Phase 2 is always authoritative.

Signs to ignore preflight:
- More than 10 errors on a skill that "looks fine"
- Errors that don't make sense (line numbers don't match)
- Python tracebacks from the script itself
- Timeouts or hanging

**When in doubt, skip preflight and let the LLM verify everything.**

## Phase 2: Audit + Fix (Single Pass) - THE CORE

This is the main phase. Work through the skill file section by section.

### 2.1 Identify the Technology

From the skill's content, identify:
- Primary technology/framework (e.g., LangGraph, React, Axum, Go-kit)
- Version constraints if mentioned
- Official documentation domain

### 2.2 Research Strategy

**Batch similar lookups** to minimize web calls:

```
Example: For a skill with 10 import statements from the same package,
do ONE search that covers them all, not 10 separate searches.
```

**Documentation priority**:
1. Official docs (use `site:` filter)
2. Official GitHub repo (examples, tests, README)
3. Package registry (PyPI, npm, crates.io, pkg.go.dev)
4. Official blog/changelog

### 2.3 For Each Verifiable Item

| Item Type | What to Verify |
|-----------|---------------|
| Import/require statement | Package exists, path is current, not deprecated |
| API call | Signature matches official docs, parameters correct |
| Code example | Would execute, complete imports, correct syntax |
| URL/link | Accessible (WebFetch), points to claimed content |
| Version claim | Current/accurate |
| Best practice claim | Aligned with official recommendations |

### 2.4 Fix-As-You-Go

When you find an issue:

1. **STOP** auditing that section
2. **FIX** the issue immediately (Edit tool)
3. **LOG** the change in memory: `{location, old, new, reason, source_url}`
4. **CONTINUE** auditing

**All severities get fixed in one pass** - don't defer anything.

### 2.5 Syntax Verification (LLM-based)

For code blocks, verify syntax by reading carefully:

**Python**: Check for matching parentheses, correct indentation, valid syntax
**JavaScript/TypeScript**: Check for matching braces, valid syntax, correct imports  
**Rust**: Check for matching braces, semicolons, valid syntax
**Go**: Check for matching braces, correct package structure
**Any language**: Apply your knowledge of that language's syntax rules

If unsure about syntax validity, note it but don't block on it - focus on semantic correctness against official docs.

## Phase 3: Verification (Spot-Check)

After completing Phase 2:

1. **Re-read the modified skill file**
2. **Spot-check 3-5 items you fixed** (not everything)
3. **Verify URLs you added/modified** (WebFetch)

If spot-checks pass → Proceed to Phase 4
If spot-checks fail → Fix those specific items, re-check only those

**Do NOT do a full re-audit.** You already verified everything in Phase 2.

## Phase 4: Generate Report

Create a concise report (<100 lines):

```markdown
# Skill Perfection Report

**Skill**: {skill-name}
**Date**: {date}  
**Version**: {old} → {new}
**Status**: ✅ PERFECTED | ⚠️ NEEDS REVIEW

## Summary
- Items verified: {N}
- Issues found and fixed: {N}

## Changes Made

### High Priority
| Location | Change | Reason | Source |
|----------|--------|--------|--------|
| line 45 | `old` → `new` | why | [docs](url) |

### Medium/Low Priority
| Location | Change | Reason | Source |
|----------|--------|--------|--------|
| line 12 | `old` → `new` | why | [docs](url) |

## Verification
- [x] All imports verified against official docs
- [x] All API signatures match current documentation
- [x] Code examples are complete and correct
- [x] All URLs accessible

## Sources
1. {url}
2. {url}
```

Save to: `{skill-directory}/PERFECTION_REPORT.md`

## Efficiency Guidelines

| Metric | Target |
|--------|--------|
| Web searches | <20 per skill (batch similar items) |
| Iterations | 1 audit+fix pass + 1 spot-check |
| Report length | <100 lines |

## Anti-Patterns

❌ Run preflight on non-Python skills
✅ Skip preflight, let LLM verify

❌ Trust confusing preflight output  
✅ Ignore preflight when output doesn't make sense

❌ Separate audit pass, then separate update pass
✅ Fix issues as you find them

❌ Full re-audit after fixes
✅ Spot-check only changed items

❌ Research same API multiple times  
✅ Batch similar lookups, cache results

## Bundled Scripts

### scripts/preflight.py

**Purpose**: Quick syntax check for Python-heavy skills
**Limitation**: Only useful for Python; advisory only

```bash
# Use for Python skills
uv run python ${SKILL_DIR}/scripts/preflight.py skill.md --no-urls

# Skip for non-Python skills or if output is confusing
```

**If preflight causes problems, ignore it entirely.** The LLM-based audit is always the authoritative verification.

© OmidZamani · MIT · OmidZamani/dspy-skills

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
system-audit gasserane Проверяет согласованность системы агентов, вики и тестового стенда. Запускается по команде /system-audit или перед /li curate. CX Codex +1 661установок audit raphaelsalaja Скилл audit для Claude Code, запускающий сводный аудит изменений по набору правил и формирующий интерактивный отчёт. Оценивает диффы, ветки, сессии или весь репозиторий. CX Codex +1 176установок press paulnsorensen Скилл press проводит враждебную проверку тестами после изменения поведения и ищет сценарий, где жалоба пользователя всё ещё воспроизводится. Рабочий код не меняет. CX Codex +1 814установок testdino-audit официальный TestDino Скилл testdino-audit проводит аудит автоматических тестов на Playwright через MCP-сервер TestDino и складывает замечания в markdown-отчёт. Включается только по прямой просьбе. CX Codex +1 ★ 4 931звёзд репо codebase-review-swarm ZaxbyHub Скилл codebase-review-swarm для Claude Code запускает аудит репозитория с опорой на цитаты кода. Проверяет безопасность, QA, доступность и AI-мусор без изменения файлов проекта. CX Codex +1 ★ 539звёзд репо Post-Implementation Audit Agent Role wkaandemir Промпт Post-Implementation Audit Agent Role превращает модель в аудитора свежих изменений: проверяет полноту реализации, тесты, риски и готовность к релизу. GP ChatGPT ★ 178 201звёзд репо

Из того же набора23

Весь набор →
dspy-simba-optimizer Скилл dspy-simba-optimizer для Claude Code и Codex оптимизирует программы DSPy методом SIMBA: по числовой метрике ищет удачные инструкции и примеры для повышения качества. CX Codex +1 ★ 125звёзд репо dspy-signature-designer Скилл dspy-signature-designer для Claude Code и Codex. Помогает описать входы и выходы модуля DSPy через типизированные сигнатуры, загоняя ответ модели в строгую схему. CX Codex +1 ★ 125звёзд репо dspy-reasoning-modules Скилл dspy-reasoning-modules помогает настроить сложные модули рассуждений в DSPy 3.2.1: RLM, ProgramOfThought, CodeAct и Parallel. Пригодится при обработке длинных контекстов и вычислениях на Python. CX Codex +1 ★ 125звёзд репо dspy-react-agent-builder Скилл dspy-react-agent-builder помогает собрать агента на DSPy ReAct, который вызывает инструменты для многошаговых задач. Он пригодится для поиска с последующим анализом, расчётов и ответов с внешними данными. CX Codex +1 ★ 125звёзд репо dspy-rag-pipeline Скилл dspy-rag-pipeline для Claude Code и Codex, строит пайплайны retrieval-augmented generation с ColBERTv2. Систематически улучшает поиск по собственному корпусу документов и факт-чекирование ответов. CX Codex +1 ★ 125звёзд репо dspy-production-deployment Скилл dspy-production-deployment учит агента развёртывать пайплайны DSPy 3.2.1 с безопасным кэшированием, асинхронным запуском, трекингом токенов и стримингом ответов в продакшене. CX Codex +1 ★ 125звёзд репо dspy-output-refinement-constraints Скилл dspy-output-refinement-constraints для Claude Code и Codex помогает проверять и итерационно дорабатывать ответы DSPy, чтобы они соответствовали формату и содержали заданные данные. CX Codex +1 ★ 125звёзд репо dspy-optimizer-selection Скилл dspy-optimizer-selection для Claude Code выбирает оптимизатор DSPy по задаче и бюджету. Матрица показывает требования: зависимости, тип данных и возможность дообучения. CX Codex +1 ★ 125звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой