🧩 Skills

A skill is a directory inside ~/.claude/skills/ with one required file SKILL.md at the root. The folder can contain subfolders (scripts/, prompting/, references/) and auxiliary files.

Understanding that a skill is a folder—and not just a file—changes how you organize knowledge. You separate rules (SKILL.md), execution (scripts/), and documentation (references/), keeping everything modular and easy to maintain.

Root directory in ~/.claude/skills/nome-da-skill/; SKILL.md required; subfolders are optional but recommended for complex skills; directory name in kebab-case.

The YAML frontmatter at the top of SKILL.md defines the skill's metadata: name (unique identifier), description (what it does and when to trigger it), and optionally triggers (explicit trigger phrases).

The frontmatter is the skill's "contract" with the agent. A weak description results in a skill that never triggers or triggers when it shouldn't. Well-written frontmatter ensures Claude Code knows exactly when to invoke the skill.

Block delimited by ---; fields name e description required; description in natural language; valid YAML without tabs.

After the frontmatter, SKILL.md contains the Markdown body with: a workflow (numbered sections), hard rules ("NEVER do X"), examples of good and bad usage, references to supporting files, and confirmation gates before irreversible actions.

The body is the skill's brain. This is where you program its detailed behavior: the order of steps, what to check, how to report results. A good body replaces dozens of repetitive manual prompts.

Sections with ## for workflows; - lists for steps; ``` blocks for code; tables for good/bad comparisons; prominent hard rules (**NEVER**); references to ./scripts/ and ./references/.

Global skills are in ~/.claude/skills/ and are available in any project. Project-local skills can live in .claude/skills/ at the repo root — scope limited to the project.

Separating global skills (reusable utilities) from project skills (repo-specific logic) avoids namespace pollution and ensures that a client’s sensitive skills don’t leak into other projects.

Global: ~/.claude/skills/; Local: .claude/skills/; Local overrides global settings with the same name; skills apply to the active context.

Claude Code scans the skills directory and injects the metadata (name + description) into the system context. When the user's message matches the description, the agent uses the Skill tool to load and run the complete SKILL.md.

Understanding the discovery mechanism explains why description is the most critical field. The agent doesn't read the skill body until it decides to activate it — the description is the only relevance signal available when it makes that decision.

Automatic scan on startup; metadata injection into the system prompt; semantic match between description and user request; lazy activation (the body is read only when activated).

Skill = reusable specialized behavior with state and rules (e.g., formato-curso). Prompt = one-off instruction with no persistence. Slash command = keyboard shortcut for a repetitive prompt. Skills load context, scripts, and references; prompts and commands don’t.

Choosing the wrong tool costs time. Did a complex 10-step workflow become a prompt? You’ll forget steps. Did you turn it into a skill? The agent ensures complete execution every time.

Skill: persistent, multi-file, with rules; Prompt: stateless, inline, disposable; Slash command: quick shortcut; Use a skill when: the workflow is complex, rules are strict, or helper scripts are needed.

The field description of the frontmatter is semantically analyzed by the agent. It compares the user's message with all available descriptions and invokes the most relevant skill. A poor description makes a skill invisible.

Without understanding how the agent uses the description, you'll write skills that never trigger or skills that compete with each other. The description is the skill's only "advertisement" — it needs to be clear, specific, and cover real-world usage scenarios.

Semantic match (not literal); description such as "announcement"; specificity > generality; include an action verb ("Use when...", "Trigger when..."); cover variations in user phrasing.

Trigger phrases are explicit clauses in the description that list activation scenarios: "Use when the user asks you to create HTML course pages", "Trigger when mentioning learning paths, modules, or INEMA.CLUB". They are the skill’s "list of use cases".

Explicit trigger phrases make activation behavior predictable and auditable. Without them, activation becomes guesswork. With them, you can test: “If I say X, should skill Y activate?”

Standard prefixes: "Use when", "Trigger when", "TRIGGER when"; list contexts (not just keywords); include domain synonyms; separate with semicolons for clarity.

SKIP clauses in the description list cases where the skill should NOT trigger, even when there is thematic overlap. E.g.: "SKIP: file imports openai, generic code without the Anthropic SDK". Defines the scope with surgical precision.

Overly generic skills trigger for everything and add noise. SKIP draws clear boundaries: the skill specializes in X, not everything that superficially looks like X. This reduces conflicts between skills and improves precision.

Explicit "SKIP:" prefix; list of anti-cases; complements TRIGGER; the more specific the skill, the less SKIP you need; negation test ("if you do Y, it should not trigger").

The folder and field name name in the frontmatter follow kebab case: lowercase letters, with words separated by hyphens. E.g., formato-curso, ads-skill, n8n-code-python.

Kebab-case is URL-safe, filesystem-safe, and visually readable in the terminal. It enables automatic slash commands (/formato-curso) and unquoted references in bash scripts. Mixing conventions creates silent bugs.

All lowercase; hyphen separator; no spaces, underscores, or camelCase; descriptive name (2-4 words); consistency between folder and frontmatter name; avoid ambiguous abbreviations.

A good description combines: (1) what the skill does in one sentence, (2) trigger phrases covering multiple phrasings, (3) SKIP to define the scope. Example from the skill claude-api: "Build, debug, and optimize Claude API apps. TRIGGER when: code imports anthropic/SDK. SKIP: openai, other-provider SDK."

Reading real examples speeds up learning more than any theory. Patterns that work in production reveal nuances that theoretical documentation leaves out: ideal length, level of specificity, and the balance between TRIGGER and SKIP.

3–6 lines of description is ideal; summary sentence + TRIGGER + SKIP; test with 5 real questions before publishing; review after using it 10 times in practice.

Poor descriptions are: (1) too generic — "Helps with code" (everything is code), (2) ambiguous — "Use when you need AI" (every skill uses AI), (3) too technical — "Processes tokens via API" (users don't think that way), (4) missing TRIGGER/SKIP — leaves the agent to guess.

Description errors cause silent problems: the skill exists but is never used, or worse, it triggers in the wrong contexts and produces unexpected results. Identifying anti-patterns saves hours of debugging.

Anti-patterns: vague, circular, too technical, lacking contextual anchors; the "1-sentence" test: can someone unfamiliar with the skill tell when to use it just by reading the description?

The subfolder scripts/ contains files .sh (or .py, .js) that the agent can run via Bash. Each script performs an atomic task: check dependencies, process files, call APIs, format output. SKILL.md references each script by its relative path.

Scripts externalize the operational logic from SKILL.md, keeping it readable. A 50-line script shouldn’t be inline in the markdown—it belongs in scripts/, and SKILL.md only describes when and how to call it.

Atomic scripts (1 script = 1 responsibility); name with verb-noun (check-deps.sh, analyze-video.sh); chmod +x required; relative path in SKILL.md (./scripts/check.sh).

Files reference.md (or in references/) contain detailed documentation: API specs, decision tables, extensive examples, decision history. SKILL.md mentions them but doesn't duplicate their contents — “see reference.md for the full table.”

SKILL.md needs to be short and easy to scan—the agent reads it in full every time it activates. Extensive details in SKILL.md increase token costs and make it harder to read. References are loaded on demand, when needed.

Short SKILL.md (50-150 lines); long references (no limit); explicit link in SKILL.md; references/ subfolder for multiple files; README.md explaining each file in the folder.

The file .env.example lists the required environment variables with example values (never real ones). The user copies them to .env and fills it in. Scripts read from $VARNAME — never hardcoded. SKILL.md instructs the agent to check whether .env exists before using the skill.

API keys in code or logs are serious vulnerabilities. .env.example is the industry standard: it documents what’s needed without exposing secrets. A skill that follows this practice won’t accidentally leak credentials.

.env.example in the repo (no real values); real .env in .gitignore; scripts use os_environ or source .env; verification gate in SKILL.md ("check whether .env exists"); hard rule "NEVER log API keys".

Progressive disclosure is the principle of showing what’s essential first and providing more detail on demand. In the context of skills: SKILL.md contains the main workflow + links to details; references/ and scripts/ contain the details. The agent decides when to dive into the extra documentation.

A 500-line SKILL.md is hard to read, expensive in tokens, and prone to internal contradictions. Progressive disclosure forces clarity: what’s always needed goes in the main file; what’s rarely needed goes in the details.

Level 1 (SKILL.md): workflow, critical rules, references; Level 2 (references/): detailed specs, extensive tables; Level 3 (scripts/): implementation; explicit links between levels; SKILL.md is always read, details are read when relevant.

Hard rules are absolute restrictions written in ALL CAPS in SKILL.md: "NEVER log the API key," "ALWAYS ask for confirmation before deleting," "NEVER paraphrase the transcript — verbatim only." They differ from guidelines (suggestions) — they are inviolable.

Hard rules protect against the costliest mistakes: data leaks, unnecessary credit spending, irreversible file loss. They are the skill's safety net — the more critical the skill, the more important its hard rules.

Formatting: capitalize “NEVER,” “ALWAYS,” “NEVER”; use a dedicated “## Hard Rules” section in SKILL.md; 3-7 rules (more than that becomes noise); give each rule a short justification; test each rule with an adversarial case.

Confirmation gates are checkpoints in the skill’s workflow where the agent pauses and asks the user before performing a costly, irreversible, or high-impact action. E.g.: "Do you confirm generating the video? (this uses 10 Arcads credits)". Implemented as explicit steps in SKILL.md.

Gates save money and time. A video generation skill without a gate can trigger 50 accidental generations in a loop. The cost of confirming is zero; the cost of not confirming can be enormous. Gates also increase the user’s trust in the skill.

Gate before costly actions ($$); gate before irreversible actions (delete, publish); show estimated cost/impact; offer an option to cancel; document gates in the "Flow" section of SKILL.md.

The ads-skill does 2 distinct things: (1) Analysis: extracts frames+audio from a UGC video via ffmpeg, identifies the HOOK→SHOW→PROOF→CTA narrative structure, and produces a viral report; (2) Generation: receives 4 inputs (image/audio/video/actor) and generates a new ad via the Arcads API, routing it through the best model.

Seeing a skill with two complementary capabilities shows how to group related functionality instead of creating 2 separate skills. Analysis + generation are inseparable in the ads workflow—analysis informs the inputs for generation.

Multimodal skill (processes video/audio/images); ffmpeg for frame extraction; 15s UGC structure: [0-2s HOOK][2-6s SHOW][6-11s PROOF][11-14s CTA][14-15s LOGO]; Arcads API for generation.

The skill routes between 4 models: Seedance 2.0 (default, best lip sync), Veo 3.1 (locked initial frame, visual consistency), Sora 2 (long/cinematic videos), Kling 3.0 (silent/aesthetic content). The routing logic is in prompting/model-routing.md.

Intelligent routing within a skill shows how SKILL.md can contain nontrivial decision logic. Instead of requiring you to know 4 models, the skill abstracts the choice with clear rules.

Seedance: default for UGC with speech; Veo: when the reference frame is critical; Sora: >30s or cinematic style; Kling: no audio, visual focus; rules in a dedicated routing file.

The ads-skill has: SKILL.md (frontmatter + flow + hard rules), scripts/arcads_check.sh, arcads_analyze.sh, arcads_actors.sh, arcads_upload.sh, arcads_generate.sh, arcads_talking.sh, arcads_status.sh + prompting/ with 3+ files reference.md + .env.example.

The ads-skill folder structure is a reference template for any skill that integrates an external API. The 7 scripts cover the full cycle: check (dependencies) → analyze (input) → actors (options) → upload (media) → generate (job) → talking (variant) → status (polling).

Scripts named with the API prefix (arcads_*); check→analyze→upload→generate→status cycle; prompting/ with 3 files (viral-analysis, ugc-formulas, model-routing); reference.md with API docs.

The 3 hard rules of the ads-skill: (1) NEVER paraphrase the video's transcript — always verbatim; (2) ALWAYS run the "dialogue gate" before generating (confirm inputs with the user to avoid wasting Arcads credits); (3) NEVER log the API key in any output or debug log.

These 3 rules protect: (1) the integrity of viral content (paraphrasing kills the timing); (2) the budget (video generation costs real money); (3) security (leaked API keys = compromised account). They’re the bare minimum for using the skill in production.

Verbatim: copy the exact text, don't summarize or rewrite; dialogue gate: confirmation screen with estimated cost; API key: read from $ARCADS_API_KEY, never print it; 3 rules = memorable and testable.

The 15s UGC framework: [0-2s HOOK] scroll-stopping pattern interrupt; [2-6s SHOW] product/benefit demonstration; [6-11s PROOF] number/result/social proof; [11-14s CTA] clear call to action; [14-15s LOGO] brand. The skill automatically identifies and extracts each segment.

The 15s UGC framework is the gold standard for viral mobile ads. Understanding it lets you evaluate existing UGC, identify weak spots, and regenerate the segments with issues — exactly what the skill does.

HOOK (0-2s): surprise, question, contradiction; SHOW (2-6s): real demo, not stock footage; PROOF (6-11s): specific number, not vague; CTA (11-14s): 1 specific action; LOGO (14-15s): quick branding.

The ads-skill puts all the concepts into practice: (3.1) folder with SKILL.md + complete anatomy; (3.2) description with TRIGGER for "analyze UGC" + SKIP for non-advertising videos + kebab-case name; (3.3) 7 atomic scripts + 3 references + .env.example + progressive disclosure + 3 hard rules + dialogue gate.

Seeing the concepts in real code removes the ambiguity of theory. Every design decision in ads-skill has a reason—and understanding the "why" behind each choice prepares you to create your own production-ready skills.

Theory (3.1-3.3) → implementation (ads-skill); each skill element maps to a concept; a good skill = checklist of the previous modules; your next skill: copy the structure, adapt the domain.