Создатель навыков

---
name: skill-creator
description: Руководство по созданию эффективных навыков. Этот навык следует использовать, когда пользователи хотят создать новый навык (или обновить существующий), расширяющий возможности Claude специализированными знаниями, рабочими процессами или интеграциями инструментов.
license: Полные условия в LICENSE.txt
---

# Создатель навыков

Этот навык предоставляет рекомендации по созданию эффективных навыков.

## О навыках

Навыки — модульные, самодостаточные пакеты, расширяющие возможности Claude с помощью
специализированных знаний, рабочих процессов и инструментов. Представляйте их как «вводные руководства» по конкретным
областям или задачам: они превращают Claude из универсального агента в специализированного,
обладающего процедурными знаниями, которыми ни одна модель не может обладать в полном объёме.

### Что предоставляют навыки

1. Специализированные рабочие процессы — многошаговые процедуры для конкретных областей
2. Интеграции инструментов — инструкции по работе с определёнными форматами файлов или API
3. Предметные знания — специфичные для компании знания, схемы, бизнес-логика
4. Включённые ресурсы — скрипты, справочные материалы и вспомогательные файлы для сложных и повторяющихся задач

## Основные принципы

### Краткость — ключевой принцип

Контекстное окно — общий ресурс. Навыки делят контекстное окно со всем остальным, что нужно Claude: системным промптом, историей разговора, метаданными других навыков и фактическим запросом пользователя.

**Предположение по умолчанию: Claude уже очень умён.** Добавляйте только тот контекст, которого у Claude ещё нет. Ставьте под сомнение каждый фрагмент информации: «Действительно ли Claude нужно это объяснение?» и «Оправдывает ли этот абзац расход токенов?»

Предпочитайте краткие примеры пространным объяснениям.

### Задавайте подходящие степени свободы

Соотносите уровень конкретности с чувствительностью задачи к ошибкам и её вариативностью:

**Высокая свобода (текстовые инструкции)**: используйте, когда допустимы несколько подходов, решения зависят от контекста или подход определяется эвристиками.

**Средняя свобода (псевдокод или скрипты с параметрами)**: используйте, когда существует предпочтительный шаблон, допускается некоторая вариативность или конфигурация влияет на поведение.

**Низкая свобода (конкретные скрипты, мало параметров)**: используйте, когда операции чувствительны к ошибкам, согласованность критически важна или необходимо соблюдать определённую последовательность.

Представьте, что Claude исследует путь: узкому мосту над обрывами нужны конкретные ограждения (низкая свобода), а открытое поле допускает множество маршрутов (высокая свобода).

### Анатомия навыка

Каждый навык состоит из обязательного файла SKILL.md и необязательных включённых ресурсов:

```
skill-name/
├── SKILL.md (обязательно)
│   ├── Метаданные YAML frontmatter (обязательно)
│   │   ├── name: (обязательно)
│   │   └── description: (обязательно)
│   └── Инструкции Markdown (обязательно)
└── Включённые ресурсы (необязательно)
    ├── scripts/          - Исполняемый код (Python/Bash/и т. д.)
    ├── references/       - Документация, загружаемая в контекст по мере необходимости
    └── assets/           - Файлы, используемые в результате (шаблоны, значки, шрифты и т. д.)
```

#### SKILL.md (обязательно)

Каждый SKILL.md состоит из:

- **Frontmatter** (YAML): содержит поля `name` и `description`. Это единственные поля, которые Claude читает, чтобы определить, когда использовать навык, поэтому крайне важно ясно и полно описывать, что представляет собой навык и когда его следует применять.
- **Основной текст** (Markdown): инструкции и рекомендации по использованию навыка. Загружается только ПОСЛЕ срабатывания навыка (если вообще загружается).

#### Включённые ресурсы (необязательно)

##### Скрипты (`scripts/`)

Исполняемый код (Python/Bash/и т. д.) для задач, требующих детерминированной надёжности или многократного переписывания одного и того же кода.

- **Когда включать**: когда один и тот же код переписывается многократно или нужна детерминированная надёжность
- **Пример**: `scripts/rotate_pdf.py` для задач поворота PDF
- **Преимущества**: экономия токенов, детерминированность, возможность выполнения без загрузки в контекст
- **Примечание**: Claude всё же может потребоваться прочитать скрипты для внесения исправлений или адаптации к среде

##### Справочные материалы (`references/`)

Документация и справочные материалы, предназначенные для загрузки в контекст по мере необходимости, чтобы направлять работу и рассуждения Claude.

- **Когда включать**: когда Claude должен обращаться к документации во время работы
- **Примеры**: `references/finance.md` для финансовых схем, `references/mnda.md` для корпоративного шаблона NDA, `references/policies.md` для политик компании, `references/api_docs.md` для спецификаций API
- **Применение**: схемы баз данных, документация API, предметные знания, политики компании, подробные руководства по рабочим процессам
- **Преимущества**: SKILL.md остаётся компактным; материалы загружаются только тогда, когда Claude определяет, что они нужны
- **Рекомендация**: если файлы большие (>10 тыс. слов), включайте в SKILL.md шаблоны поиска grep
- **Избегайте дублирования**: информация должна находиться либо в SKILL.md, либо в справочных файлах, но не в обоих местах.

##### Вспомогательные файлы (`assets/`)

Файлы, предназначенные не для загрузки в контекст, а для использования в результате, который создаёт Claude.

- **Когда включать**: когда навыку нужны файлы, которые будут использованы в итоговом результате
- **Примеры**: `assets/logo.png` для фирменных материалов, `assets/slides.pptx` для шаблонов PowerPoint
- **Применение**: шаблоны, изображения, значки, шаблонный код, шрифты, образцы документов

### Принцип постепенного раскрытия

Навыки используют трёхуровневую систему загрузки для эффективного управления контекстом:

1. **Метаданные (name + description)** — всегда в контексте (~100 слов)
2. **Основной текст SKILL.md** — при срабатывании навыка (<5 тыс. слов)
3. **Включённые ресурсы** — по мере необходимости для Claude

Оставляйте в основном тексте SKILL.md только существенное и удерживайте его объём в пределах 500 строк, чтобы свести разрастание контекста к минимуму.

## Процесс создания навыка

Создание навыка включает следующие шаги:

1. Понять навык на конкретных примерах
2. Спланировать повторно используемое содержимое навыка (скрипты, справочные материалы, вспомогательные файлы)
3. Инициализировать навык (запустить init_skill.py)
4. Отредактировать навык (реализовать ресурсы и написать SKILL.md)
5. Упаковать навык (запустить package_skill.py)
6. Последовательно улучшать его на основе реального использования

### Шаг 3: инициализация навыка

При создании нового навыка с нуля всегда запускайте скрипт `init_skill.py`:

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

### Шаг 4: редактирование навыка

Обращайтесь к этим полезным руководствам в зависимости от потребностей навыка:

- **Многошаговые процессы**: см. references/workflows.md о последовательных рабочих процессах и условной логике
- **Конкретные форматы вывода или стандарты качества**: см. references/output-patterns.md о шаблонах и примерах

### Шаг 5: упаковка навыка

```bash
scripts/package_skill.py <path/to/skill-folder>
```

Скрипт упаковки выполняет проверку и создаёт файл .skill для распространения.

# Шаблоны рабочих процессов

## Последовательные рабочие процессы

Для сложных задач разбивайте операции на понятные последовательные шаги. Часто полезно дать Claude обзор процесса ближе к началу SKILL.md:

```markdown
Заполнение PDF-формы включает следующие шаги:

1. Проанализировать форму (запустить analyze_form.py)
2. Создать сопоставление полей (отредактировать fields.json)
3. Проверить сопоставление (запустить validate_fields.py)
4. Заполнить форму (запустить fill_form.py)
5. Проверить результат (запустить verify_output.py)
```

## Условные рабочие процессы

Для задач с ветвящейся логикой проводите Claude через точки принятия решений:

```markdown
1. Определить тип изменения:
   **Создаётся новое содержимое?** → Следовать «Рабочему процессу создания» ниже
   **Редактируется существующее содержимое?** → Следовать «Рабочему процессу редактирования» ниже

2. Рабочий процесс создания: [steps]
3. Рабочий процесс редактирования: [steps]
```

# Шаблоны вывода

Используйте эти подходы, когда навыки должны выдавать согласованный результат высокого качества.

## Подход с шаблоном

Предоставляйте шаблоны формата вывода. Соотносите степень строгости с вашими потребностями.

**Для строгих требований (например, к ответам API или форматам данных):**

```markdown
## Структура отчёта

ВСЕГДА используйте именно эту структуру шаблона:

# [Analysis Title]

## Краткое резюме
[One-paragraph overview of key findings]

## Ключевые выводы
- Вывод 1 с подтверждающими данными
- Вывод 2 с подтверждающими данными
- Вывод 3 с подтверждающими данными

## Рекомендации
1. Конкретная рекомендация, которую можно реализовать
2. Конкретная рекомендация, которую можно реализовать
```

**Для гибких указаний (когда полезна адаптация):**

```markdown
## Структура отчёта

Ниже — разумный формат по умолчанию, но руководствуйтесь собственным суждением:

# [Analysis Title]

## Краткое резюме
[Overview]

## Ключевые выводы
[Adapt sections based on what you discover]

## Рекомендации
[Tailor to the specific context]

При необходимости корректируйте разделы под конкретный тип анализа.
```

## Подход с примерами

Для навыков, качество результата которых зависит от наличия примеров, предоставляйте пары «входные данные/результат»:

```markdown
## Формат сообщения коммита

Создавайте сообщения коммитов по следующим примерам:

**Пример 1:**
Входные данные: добавлена аутентификация пользователей с помощью JWT-токенов
Результат:
```
feat(auth): реализовать аутентификацию на основе JWT

Добавить конечную точку входа и промежуточный обработчик проверки токенов
```

**Пример 2:**
Входные данные: исправлена ошибка, из-за которой даты в отчётах отображались неправильно
Результат:
```
fix(reports): исправить форматирование дат при преобразовании часовых поясов

Последовательно использовать метки времени UTC при формировании отчётов
```

Следуйте этому стилю: type(scope): краткое описание, затем подробное объяснение.
```

Примеры помогают Claude понять желаемый стиль и уровень подробности яснее, чем одни лишь описания.

#!/usr/bin/env python3
"""
Quick validation script for skills - minimal version
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """Basic validation of a skill"""
    skill_path = Path(skill_path)

    # Check SKILL.md exists
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "SKILL.md not found"

    # Read and validate frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "No YAML frontmatter found"

    # Extract frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "Invalid frontmatter format"

    frontmatter_text = match.group(1)

    # Parse YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "Frontmatter must be a YAML dictionary"
    except yaml.YAMLError as e:
        return False, f"Invalid YAML in frontmatter: {e}"

    # Define allowed properties
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}

    # Check for unexpected properties (excluding nested keys under metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # Check required fields
    if 'name' not in frontmatter:
        return False, "Missing 'name' in frontmatter"
    if 'description' not in frontmatter:
        return False, "Missing 'description' in frontmatter"

    # Extract name for validation
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"Name must be a string, got {type(name).__name__}"
    name = name.strip()
    if name:
        # Check naming convention (hyphen-case: lowercase with hyphens)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
        # Check name length (max 64 characters per spec)
        if len(name) > 64:
            return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."

    # Extract and validate description
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"Description must be a string, got {type(description).__name__}"
    description = description.strip()
    if description:
        # Check for angle brackets
        if '<' in description or '>' in description:
            return False, "Description cannot contain angle brackets (< or >)"
        # Check description length (max 1024 characters per spec)
        if len(description) > 1024:
            return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."

    return True, "Skill is valid!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("Usage: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)

#!/usr/bin/env python3
"""
Skill Initializer - Creates a new skill from template

Usage:
    init_skill.py <skill-name> --path <path>

Examples:
    init_skill.py my-new-skill --path skills/public
    init_skill.py my-api-helper --path skills/private
    init_skill.py custom-skill --path /custom/location
"""

import sys
from pathlib import Path


SKILL_TEMPLATE = """---
name: {skill_name}
description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
---

# {skill_title}

## Overview

[TODO: 1-2 sentences explaining what this skill enables]

## Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

### scripts/
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

### references/
Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

### assets/
Files not intended to be loaded into context, but rather used within the output Claude produces.

---

**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
"""

EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
Example helper script for {skill_name}

This is a placeholder script that can be executed directly.
Replace with actual implementation or delete if not needed.
"""

def main():
    print("This is an example script for {skill_name}")
    # TODO: Add actual script logic here

if __name__ == "__main__":
    main()
'''

EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}

This is a placeholder for detailed reference documentation.
Replace with actual reference content or delete if not needed.
"""

EXAMPLE_ASSET = """# Example Asset File

This placeholder represents where asset files would be stored.
Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
"""


def title_case_skill_name(skill_name):
    """Convert hyphenated skill name to Title Case for display."""
    return ' '.join(word.capitalize() for word in skill_name.split('-'))


def init_skill(skill_name, path):
    """Initialize a new skill directory with template SKILL.md."""
    skill_dir = Path(path).resolve() / skill_name

    if skill_dir.exists():
        print(f"❌ Error: Skill directory already exists: {skill_dir}")
        return None

    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"✅ Created skill directory: {skill_dir}")
    except Exception as e:
        print(f"❌ Error creating directory: {e}")
        return None

    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)

    skill_md_path = skill_dir / 'SKILL.md'
    try:
        skill_md_path.write_text(skill_content)
        print("✅ Created SKILL.md")
    except Exception as e:
        print(f"❌ Error creating SKILL.md: {e}")
        return None

    try:
        scripts_dir = skill_dir / 'scripts'
        scripts_dir.mkdir(exist_ok=True)
        example_script = scripts_dir / 'example.py'
        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
        example_script.chmod(0o755)
        print("✅ Created scripts/example.py")

        references_dir = skill_dir / 'references'
        references_dir.mkdir(exist_ok=True)
        example_reference = references_dir / 'api_reference.md'
        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
        print("✅ Created references/api_reference.md")

        assets_dir = skill_dir / 'assets'
        assets_dir.mkdir(exist_ok=True)
        example_asset = assets_dir / 'example_asset.txt'
        example_asset.write_text(EXAMPLE_ASSET)
        print("✅ Created assets/example_asset.txt")
    except Exception as e:
        print(f"❌ Error creating resource directories: {e}")
        return None

    print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
    return skill_dir


def main():
    if len(sys.argv) < 4 or sys.argv[2] != '--path':
        print("Usage: init_skill.py <skill-name> --path <path>")
        sys.exit(1)

    skill_name = sys.argv[1]
    path = sys.argv[3]

    print(f"🚀 Initializing skill: {skill_name}")
    print(f"   Location: {path}")
    print()

    result = init_skill(skill_name, path)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Skill Packager - Creates a distributable .skill file of a skill folder

Usage:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

Example:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path
from quick_validate import validate_skill


def package_skill(skill_path, output_dir=None):
    """Package a skill folder into a .skill file."""
    skill_path = Path(skill_path).resolve()

    if not skill_path.exists():
        print(f"❌ Error: Skill folder not found: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ Error: Path is not a directory: {skill_path}")
        return None

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ Error: SKILL.md not found in {skill_path}")
        return None

    print("🔍 Validating skill...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ Validation failed: {message}")
        print("   Please fix the validation errors before packaging.")
        return None
    print(f"✅ {message}\n")

    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            for file_path in skill_path.rglob('*'):
                if file_path.is_file():
                    arcname = file_path.relative_to(skill_path.parent)
                    zipf.write(file_path, arcname)
                    print(f"  Added: {arcname}")

        print(f"\n✅ Successfully packaged skill to: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ Error creating .skill file: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 Packaging skill: {skill_path}")
    if output_dir:
        print(f"   Output directory: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()