skill-master

name	skill-master
description	Guide for creating/updating skills with specialized knowledge and workflows. Use when: "создай скилл", "измени скилл", "гайд по скиллам", "обнови скилл", "улучши скилл", "create skill", "update skill", "skill guide", "new skill", "how to write a skill"

Skill Creator

Claude-to-Codex Autosync

Global methodology source of truth is Claude-side: ~/.claude/**. Codex-side ~/.codex/** is generated runtime.

When changing global methodology files under ~/.claude/skills/**, ~/.claude/agents/**, ~/.claude/commands/**, or ~/.claude/shared/**, immediately run:

~/.claude/scripts/sync-to-codex.sh --apply

If sync reports a conflict or validation error, stop and report it. Include generated ~/.codex/** changes in the same commit as the ~/.claude/** source change.

When changing project-local .claude/** files inside a project, run project sync instead:

Project source of truth is Claude-side: CLAUDE.md and .claude/**. Codex-side AGENTS.md and .codex/** is generated runtime.

~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply

Built into framework skills — add it to your own. Every skill in this framework that edits .claude/** already carries an autosync step: it writes the Claude-side source first, then regenerates the Codex runtime (and the ~/.claude pre-commit hook runs the sync automatically when methodology files are staged). When you author your OWN skill that creates or edits ~/.claude/** or project .claude/** files, paste this block near the top of its SKILL.md so your changes reach Codex too:

## Autosync to Codex

This skill edits Claude-side source of truth (`~/.claude/**` for global skills, or a project's `.claude/**`). Codex-side `~/.codex/**` / `AGENTS.md` is generated runtime. After editing those files, regenerate Codex:

```bash
~/.claude/scripts/sync-to-codex.sh --apply                   # global ~/.claude/**
~/.claude/scripts/sync-to-codex.sh --project "$PWD" --apply  # project .claude/**
```

Commit the generated `.codex/**` / `AGENTS.md` changes together with the source. If sync reports a conflict, stop and report it.

If a skill never touches .claude/** (pure analysis, code-writing in a project's own source tree), it does not need an autosync block.

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks

Skill Types

There are two types of skills based on how they guide Claude's work.

Procedural Skills

Use when the task requires a strict sequence of steps where order matters. Phase 2 depends on Phase 1 completing correctly. Skipping or reordering steps would break the workflow.

Examples: code-writing (Plan → TDD → Review), project-planning (Interview → Features → Roadmap), tech-spec-planning.

These skills have explicit phases with checkpoints after each phase to verify completion before proceeding.

Creating a procedural skill? Read procedural-skills.md — phase structure, checkpoints, verification patterns.

Informational Skills

Use when providing methodology, knowledge, or guidelines without a strict execution order. The agent reads relevant sections and applies them to the situation. There's no "Phase 1 must complete before Phase 2" — sections are independent.

Examples: security-auditor (what to check), testing (when to use which test type), company-info (domain knowledge), database-schemas.

These skills organize content into logical sections with decision frameworks (YES if / NO if) to help the agent choose what applies.

Creating an informational skill? Read informational-skills.md — section organization, knowledge structure.

1. Discovery

For new skills or major changes — run discovery interview:

• What problem does the skill solve?
• What phrases should trigger it?
• What should the skill NOT do?
• Concrete usage examples

When running user interview, read interview-guide.md — process overview, example questions for each phase, handling "I don't know" answers.

Checkpoint: Requirements gathered. Problem, triggers, scope, and examples documented.

2. Skill Structure

Anatomy of a Skill

Every skill consists of a required SKILL.md file and optional bundled resources:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)

Frontmatter

name (required):

• kebab-case (lowercase, hyphens)
• ≤64 characters
• Unique identifier

description (required):

• Third person ("Analyzes code...", NOT "I analyze...")
• Include both WHAT the skill does AND WHEN to use it
• ≤1024 characters

Description Best Practices

Claude uses description to decide when to auto-invoke the skill. Be specific and include key terms.

Template:

description: |
  [What the skill does — be specific, include key terms]

  Use when: [trigger conditions — specific phrases users say]

Rules:

1. Be specific — Include key terms that match user requests
2. List trigger phrases — Real phrases users actually say (5-10 phrases)
3. Include variations — "tech-spec" AND "write a spec" (different ways to say same thing); include the user's own language alongside English

Bad:

description: This skill helps with documents. Use when user wants to work with docs.

Why bad: Vague phrases ("work with docs"), no specific triggers.

Good:

description: |
  Manage .claude/skills/project-knowledge/ docs: create, check, update.

  Use when: "заполни документацию", "создай документацию", "проверь документацию", "обнови документацию"

Why good: Specific actions, concrete trigger phrases.

How to gather trigger phrases:

1. Think: "What would I actually say to invoke this skill?"
2. Ask: "How would different users phrase this request?"
3. Include: Common typos, informal variants, English plus the user's own language if applicable

Undertriggering Problem

Claude tends to undertrigger skills — not use them when they'd be useful. To combat this, make descriptions slightly "pushy": explicitly list contexts and keywords that should activate the skill, even non-obvious ones.

Instead of:

description: How to build a dashboard to display data.

Write:

description: |
  How to build a dashboard to display data. Use this skill whenever
  the user mentions dashboards, data visualization, internal metrics,
  or wants to display any kind of data, even if they don't explicitly
  ask for a "dashboard".

Need argument-hint, disable-model-invocation, or model override? Read frontmatter-options.md — optional fields and when to use each.

Body

Every SKILL.md body consists of:

• Core workflow — main instructions that are always needed
• Links to references — for optional/detailed information
• Keep under 500 lines (otherwise → split to references)

When defining output format, read output-patterns.md — template pattern, examples pattern.

Checkpoint: SKILL.md created with frontmatter, body, and references. Skill structure complete.

Bundled Resources

A skill contains only SKILL.md and these three optional directories — nothing else (no README, CHANGELOG, etc.).

Scripts (scripts/)

Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.

• When to include: When the same code is being rewritten repeatedly or deterministic reliability is needed
• Example: scripts/rotate_pdf.py for PDF rotation tasks
• Benefits: Token efficient, deterministic, may be executed without loading into context
• Note: Scripts may still need to be read by Claude for patching or environment-specific adjustments

Concrete example: When building a pdf-editor skill for queries like "Help me rotate this PDF":

1. Rotating a PDF requires re-writing the same code each time
2. A scripts/rotate_pdf.py script solves this — write once, execute many times

How to spot script candidates: After running test cases, read the transcripts. If all test runs independently wrote similar helper code (e.g., each created a create_docx.py), that's a strong signal to bundle that script. Write once, use on every invocation.

References (references/)

Content needed in some execution paths, not all. If the skill branches (multiple operations, domains, modes) — each branch's details go to a reference. Content needed on every execution stays in SKILL.md.

Example: Task-management skill handles "create" and "edit". Each operation's workflow → separate reference. Task file format used by both → stays in SKILL.md.

• No duplication: Content lives in either SKILL.md or references, not both

How to link references in SKILL.md:

Embed references in workflow where they're logically needed. Two linking patterns, ranked by strength:

Pattern A: Action-embedded (strong) — the workflow step's action IS applying the reference content. The agent cannot complete the step without loading the file.

3. Write tests following patterns from [testing-guide.md](references/testing-guide.md)
   (test structure, naming, what to skip)

4. Apply audit criteria from [principles.md](references/principles.md) to each file
   (code examples, obvious content, generic explanations)

Why it works: "follow patterns from X" or "apply criteria from X" makes the reference part of the action, not a separate read-then-do instruction.

Pattern B: Condition + contents (basic) — for optional references needed only in specific scenarios. Each link explains WHEN to read and WHAT's inside.

**For tracked changes**, see [REDLINING.md] — revision marks, accept/reject.
**First time with docx-js?** Read [DOCX-JS.md] — setup, examples, pitfalls.

Use Pattern A for references that contain rules/patterns the agent must follow during a step. Use Pattern B for references that are only relevant in certain branches of the workflow.

Anti-pattern: Resource catalog at end of file. A passive list of references separated from the workflow. The agent reads the workflow top-down, gets instructions, and treats the catalog as optional appendix.

❌ Bad — passive catalog (ignored):
## Resources
### references/structure.md
Complete description of all files...
### references/principles.md
Quality principles...

✅ Good — embed each reference into the workflow step where it's needed:
4. Apply audit criteria from [principles.md](references/principles.md) to each file

Bad (passive, no trigger):

• Detailed guide: [X.md]
• See [X.md] for details
• Finance: [finance.md] (no context why to read)

Good (embedded in action or conditional):

• 3. Write tests following patterns from [testing-guide.md] (action-embedded)
• **Working with finance?** Read [finance.md] — P&L rules, ARR formulas (conditional)
• 4. Apply criteria from [principles.md] to each file (action-embedded)

Assets (assets/)

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

• When to include: When the skill needs files that will be used in the final output
• Examples: assets/logo.png for brand assets, assets/slides.pptx for PowerPoint templates, assets/frontend-template/ for HTML/React boilerplate
• Use cases: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
• Benefits: Separates output resources from documentation, enables Claude to use files without loading them into context

Concrete example: When designing a frontend-webapp-builder skill for queries like "Build me a todo app":

1. Writing a frontend webapp requires the same boilerplate HTML/React each time
2. An assets/hello-world/ template with boilerplate project files solves this — copy and customize

3. Writing Guidelines

Concise is Key

The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

Default assumption: Claude is already very smart. Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"

Prefer concise examples over verbose explanations.

Keep it Lean

Remove things that aren't pulling their weight. After running test cases, read the transcripts — not just the final outputs. If the skill is making the model waste time doing unproductive things, remove those parts of the skill.

Every instruction has a cost. If removing an instruction doesn't degrade results, it was dead weight.

Generalize, Don't Overfit

Skills are used across many different prompts and contexts. When iterating on a skill based on test results, resist fiddly changes targeted at specific examples. Rather than oppressively constrictive rules, try branching out — use different metaphors, recommend different patterns of working. It's cheap to try and you might land on something better.

If a skill works only for its test cases, it's useless at scale.

Degrees of Freedom

Match the level of specificity to the task's fragility and variability:

High freedom (text-based instructions): Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.

Medium freedom (pseudocode or scripts with parameters): Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.

Low freedom (specific scripts, few parameters): Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.

Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).

Progressive Disclosure

Skills use a three-level loading system to manage context efficiently:

1. Metadata (name + description) — Always in context (~100 words)
2. SKILL.md body — When skill triggers (<5k words)
3. Bundled resources — As needed by Claude (unlimited, scripts execute without reading)

Keep SKILL.md body under 500 lines. Split content into separate files when approaching this limit. When splitting, reference them from SKILL.md and describe clearly when to read them.

Key principle: When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate reference files.

Pattern 1: High-level guide with references

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features

**For form filling?** Read [FORMS.md](FORMS.md) — interactive fields, validation, PDF/A.

For complete API reference, see [REFERENCE.md](REFERENCE.md) — all methods with examples.

Claude loads FORMS.md or REFERENCE.md only when needed.

Pattern 2: Domain-specific organization

For skills with multiple domains, organize content by domain:

bigquery-skill/
├── SKILL.md (overview and navigation)
└── references/
    ├── finance.md (revenue, billing metrics)
    ├── sales.md (opportunities, pipeline)
    └── product.md (API usage, features)

In SKILL.md, link each domain with description:

When working with finance data, read finance.md — P&L rules, revenue calculations, ARR formulas.

For sales data analysis, see sales.md — opportunity stages, pipeline calculations, account hierarchies.

Working with product metrics? Read product.md — API usage tracking, feature adoption, user segments.

Pattern 3: Conditional details

# DOCX Processing

## Creating documents
Use docx-js for basic operations.

**First time with docx-js?** Read [DOCX-JS.md](DOCX-JS.md) — setup, examples, pitfalls.

## Editing documents
For simple edits, modify XML directly.

For tracked changes, see [REDLINING.md](REDLINING.md) — revision marks, accept/reject logic.

Important guidelines:

• Keep references one level deep from SKILL.md
• For files longer than 100 lines, include a table of contents at the top

Writing Approach

Start by writing a draft, then look at it with fresh eyes and improve. Use theory of mind — make the skill general, not super-narrow to specific examples. Try to explain to the model why things are important in lieu of heavy-handed constraints.

Positive over Negative

Default to positive instructions — they're followed more reliably. Rewrite negatives when the positive form fully conveys the meaning.

Rewrite when positive form is sufficient:

• "Don't use bullet points" → "Write in prose paragraphs"
• "Don't use var" → "Use const/let"

Keep negatives for hard boundaries where the positive rewrite loses the prohibition:

• Security: "Store secrets in .env" alone doesn't convey "never commit them to git" — you need both
• Irreversible damage: "Don't use --force on shared branches" — the cost of violation is high
• Disambiguation: "Use Array.from(), not spread for NodeList" — negative clarifies which similar option is wrong
• Scope limits: "This skill does not handle deployment" — defines boundary

Test: "Does the positive rewrite fully convey the prohibition?" If no → keep the negative + add motivation (WHY it matters).

Explain the Why

Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions. Try to explain the why behind everything you're asking the model to do. Even if user feedback is terse, try to actually understand the task and why the user wrote what they wrote, then transmit this understanding into the instructions.

Bad: "Always return JSON format." Good: "Return findings as JSON — orchestrator parses this automatically, invalid JSON crashes pipeline."

When explaining is impractical, keep the rule as-is. But default to reasoning over commanding.

Avoid Emphasis Words

Words like CRITICAL, MANDATORY, NEVER, IMPORTANT, MUST are anti-patterns in skills.

Why they don't work:

• Every instruction in a skill is already important — if it wasn't, it shouldn't be there
• When everything is emphasized — nothing stands out
• Emphasis words signal poorly written instructions that need rewriting, not shouting

What to do instead:

• Write clear, specific instructions
• Explain why something matters (see "Explain the Why" above)
• Use structure (steps, checkpoints) to ensure compliance

If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag — reframe and explain the reasoning so that the model understands why the thing you're asking for is important.

Hard limit: Maximum one emphasis word per skill. Ideal: zero.

Delegating Heavy Work

If skill has context-heavy tasks (reviews, research, validation):

• Keep each skill focused on a single methodology
• Delegate heavy subtasks to agents with fresh context
• Orchestrator calls agents → they work isolated → return results

When to use subagents:

• Reviews — code-reviewer, security-auditor, test-reviewer check work with fresh context
• Research — exploring codebase, reading documentation, searching information
• Debugging — isolated context for error diagnosis and root cause analysis
• Validation — checking schemas, formats, requirements compliance
• Parallel tasks — multiple independent investigations simultaneously
• High-volume output — tests, logs, reports that would bloat main context

Two approaches:

1. Inline prompts — for simple, one-off tasks (<50 lines):

   Use general-purpose/explore/plan subagent to find all TypeScript files importing {module}
   

2. Skill + Agent pattern — for complex, reusable tasks (>50 lines):

   • Skill holds methodology (WHAT to do, HOW to analyze)
   • Agent adds isolation + output format (runs in isolated context)
   • Agent uses skills: field to preload methodology
   • Reference by name: "Use code-reviewer agent"

Key principle: Keep detailed agent prompts out of SKILL.md. Large prompts bloat the skill and waste context. Store specialized agent definitions separately; the skill just invokes them.

Delegating work to subagent? Read agents.md — inline prompts, dedicated agents, output contracts.

Checkpoint: Writing guidelines applied. Skill is concise, well-structured, references linked properly.

4. Validation

Run skill-checker

After self-check — run validation:

Use skill-checker subagent to validate the skill at {path}.
If issues found → fix them → run skill-checker again.

skill-checker is defined in ~/.claude/agents/skill-checker.md and has skill-master preloaded.

Test the Skill

After creating or significantly updating a skill, suggest to the user to run skill-tester on it. skill-tester will design test cases, run them with and without the skill, test description triggering accuracy, and produce a report with specific improvement recommendations.

Self-Check Before Validation

Universal (all skills):

• name in kebab-case, ≤64 chars
• description < 1024 chars, includes "Use when:" with trigger phrases
• SKILL.md < 500 lines
• All referenced files exist
• No extra docs (README, CHANGELOG)
• References contain only conditional content (not needed on every execution path)
• References linked as action steps or with condition + contents (no passive links, no resource catalogs at end of file)
• Defaults to positive instructions. Negatives only for hard boundaries (security, irreversible damage, disambiguation, scope limits) with motivation
• No emphasis words (CRITICAL, MANDATORY, NEVER) — max one allowed

Identify skill type: procedural or informational?

If Procedural:

• Has explicit phases with numbered steps
• Has checkpoints after each phase
• Has self-verification section at end
• Uses subagent verification for critical operations (if applicable)

If Informational:

• Sections organized by logic, not sequence
• Decision frameworks present (YES if / NO if) where applicable
• No forced sequential structure

Functional (all skills):

• Run skill-checker and fix all issues