CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude Code plugin containing AI agent skills covering engineering, marketing, and productivity domains. The repository provides reusable skill definitions that Claude Code can invoke across projects.

Project Structure

skills/               # Claude Code skill definitions
  <skill-name>/
    SKILL.md          # Required: metadata + instructions
    references/       # Optional: detailed documentation loaded on demand
    scripts/          # Optional: executable code
    assets/           # Optional: templates, resources, config files, etc.
.claude-plugin/       # Plugin metadata and configuration
.cursor-plugin/       # Plugin metadata and configuration (version must match .claude-plugin/plugin.json)
gemini-extension.json # Gemini CLI extension manifest (version must match .claude-plugin/plugin.json)

Agent Skills Specification

All skills MUST conform to the Agent Skills specification. Key requirements are summarized below; the spec is the source of truth when in doubt.

Frontmatter

New skills go in skills/<skill-name>/SKILL.md. Each SKILL.md has YAML frontmatter. Fields per the Agent Skills spec — this project requires all fields marked "Project-required":

Choosing user-invocable: Use false (contextual) for domain expertise that enriches any relevant conversation without being explicitly asked — code style, security patterns, brand voice, commit conventions. Use true (user-invocable) for multi-step workflows the user explicitly triggers — ghostwriting a post, running a full audit, generating a commit message.

Example frontmatter:

---
name: skill-example
description: "Skill for X. Use when doing Y."
user-invocable: false
license: MIT
compatibility: Designed for Claude Code or similar AI coding agents. Requires git.
metadata:
  author: samber
  version: "1.0.0"
  openclaw:
    emoji: "🔧"
    homepage: https://github.com/samber/cc-skills
    install:
      - kind: brew
        formula: jq
        bins: [jq]
    requires:
      bins:
        - git
        - jq
    skill-library-version: "1.2.3"
allowed-tools: Read Edit Write Glob Grep Bash(git:*) Agent
---

ClawHub metadata (metadata.openclaw)

All skills MUST include metadata.openclaw fields for ClawHub discoverability and dependency management. See the ClawHub skill format spec for the full reference.

install describes how to get a dependency. requires.bins declares what must exist at runtime. A skill can have requires.bins without install (e.g. git — assumed pre-installed) or both (e.g. promql — installable via go install).

Version discipline: Versions follow semver (a.b.c). New skills start at 1.0.0. When modifying a skill, the developer must increment its metadata.version and the plugin version in .claude-plugin/plugin.json before merging. CI enforces both checks on PRs. Do not auto-increment versions — remind the developer as a next step.

Description quality

Descriptions are the primary triggering mechanism — they determine whether a skill activates or stays silent. A poorly calibrated description wastes context (too broad) or never fires (too vague).

Too vague (under-triggering) — one-liner descriptions without "Use when..." clauses. The model cannot match user intent to the skill. Fix by adding specific trigger scenarios, API names, and tool names.

# Bad — no trigger context, will be ignored
description: Implements X using library/foo

# Good — specific triggers, matches real user activity
description: Implements X using library/foo — feature A, feature B, and feature C. Apply when using or adopting library/foo.

Too broad (over-triggering) — phrases like "whenever writing code", "when naming any identifier", "essential for ANY conversation". These match virtually all work and flood the context with irrelevant skills. Fix by narrowing to the specific concern the skill uniquely addresses.

# Bad — triggers on all coding work
description: Use when writing code, reviewing style, or writing comments.

# Good — triggers only when style is the actual concern
description: Typescript style conventions. Use when the user explicitly asks about formatting, style review, or project coding standards.

Overlap (competing triggers) — when two skills claim the same trigger keywords, the model may load the wrong one. Fix by adding explicit boundary disclaimers with → See cross-references.

# Good — clear boundary
description: "...Not for measurement methodology (→ See skill-name skill)."

Library-specific skills follow a consistent pattern: describe what the library does, list key API surface, then "Apply when using or adopting X, or when the codebase imports Y." This is the gold standard for contextual (non-user-invocable) skills.

Tool and platform-specific skills (non-engineering) follow the same idea but without import paths: describe what the platform or format does, list key concepts and output types, then "Apply when the user mentions X, wants to publish on Y, or needs to follow Z conventions." Example: linkedin-ghostwriting — "Apply when the user wants to write LinkedIn content, create ghostwritten posts, or develop a B2B social strategy."

Allowed Tools

Every skill MUST declare an allowed-tools field. Start from the default set and add skill-specific extras as needed.

Default tools (include in every skill):

Read Edit Write Glob Grep Agent

Skill-specific extras — add only when relevant:

When creating a new skill, suggest a tailored allowed-tools list based on the skill's purpose.

Skill Body

The body contains step-by-step instructions. Use secondary markdown files in references/ for depth (referenced via relative links like [Details](references/details.md)). Keep file references one level deep from SKILL.md — avoid deeply nested reference chains. For engineering skills this typically means command references, API docs, and usage examples; for content skills it means writing frameworks, worked examples, hook libraries, and editorial templates.

Important: When including non-markdown content (configuration files, scripts, templates, linter configs, etc.), create them as separate files in assets/ rather than embedding them directly in markdown. Reference these files from your markdown using relative links (e.g., [View config](assets/example.yml)). This keeps markdown files clean, makes assets reusable, and allows proper syntax highlighting when the files are viewed separately.

Token budgets

• ~100 tokens per description — loaded at startup for all skills
• < 5.000 tokens per SKILL.md (spec recommendation) — keep focused on essentials
• < 2.500 tokens per SKILL.md (project recommendation)
• < 500 lines per SKILL.md — move detailed reference material to references/
• Use secondary markdown files for depth — Claude reads these on demand, so they don't count against context until needed
• 2-4 skills loaded simultaneously in a typical session
• Stay below ~10k tokens of total loaded SKILL.md to avoid degrading response quality

This is a budget. A 100 lines SKILL.md is even better. Feel free to stay far below the limits.

Top-of-body directives

Place these directives at the very top of the body, before the first heading, in this order:

All three are optional. A short procedural skill may have none. A complex orchestrating skill may have all three.

Persona (optional)

Place **Persona:** at the very top of the body, before any heading. Keep it to 1–2 sentences: role → mindset or goal. No fictional biography.

**Persona:** You are a <role>. <Mindset/assumption or goal>.

Include a persona when:

• The skill has a well-defined analytical or generative domain (security, performance, debugging) — it primes the model to prioritize angles it would otherwise reach only with longer prompts.
• The skill is invoked by multiple distinct user types or tasks (reviewer vs. builder, auditor vs. coder) — a persona helps the model adopt the right frame for each invocation context.
• The skill produces stylistic output (docs, code review, commit messages) — it maintains tone consistency across invocations.
• The skill orchestrates sub-agents — it implicitly defines the delegation policy and conflict resolution strategy.

Skip a persona when:

• The skill is purely procedural ("run X, read Y, output Z") — there is nothing to anchor.
• The skill body is very short (~10 lines) — instruction density matters more.

Risk: A persona that is too rich in a leaf skill can override global CLAUDE.md instructions if the model perceives an identity conflict. Keep leaf personas minimal and orthogonal to the global persona.

Examples:

• security-audit (audit + coding, orchestrator): You are a senior application security engineer. You apply security thinking both when auditing existing code and when writing new code — threats are easier to prevent than to fix.
• performance-profiling (analytical, orchestrator): You are a performance engineer. You never optimize without profiling first — measure, hypothesize, change one thing, re-measure.
• linkedin-ghostwriting (generative + interviewing): You are a B2B ghostwriter. You extract authentic, quantified stories and turn them into high-conversion LinkedIn posts — results first, vanity metrics never.
• content-strategy (analytical + generative): You are a content strategist. You start from audience intent and business goals, not from what is easy to write.
• code-style (procedural/short) → skip persona.

Skill modes and parallelization (optional)

Some skills serve multiple distinct modes — e.g. backend-security is used both for auditing existing code and for writing new secure code. Skills that have multiple modes SHOULD add a short "Modes" section early in their body naming each mode and its execution strategy.

Common mode names and their strategies:

When to parallelize with sub-agents:

Sub-agents can be used in three complementary ways:

1. Split by concern — each agent handles one type of search or analysis in parallel. Agents may read the same file independently; that is expected and acceptable.

   Example — backend-security audit mode (up to 5 agents):

   • Agent 1 — injection (SQL, command, LDAP): grep for dynamic query construction, shell calls with user input
   • Agent 2 — auth & authorization: JWT handling, session management, middleware chains
   • Agent 3 — cryptography: hardcoded secrets, weak hash algorithms, insecure random
   • Agent 4 — dependencies: known CVEs in lockfile, outdated packages
   • Agent 5 — input validation & error leakage: stack traces in responses, overly verbose errors

2. Split by scope — each agent covers a different part of the codebase doing the same task. Useful for large repositories where one agent would miss files.

   Example — performance-profiling across a monorepo: Agent 1 covers repositories/, Agent 2 covers services/, Agent 3 covers jobs/.

3. Background agents — run analysis (e.g., security checks, lint, test coverage) in the background while the main agent continues coding. The background agent does not block the primary workflow; its results are surfaced when it completes. Use this pattern when the analysis is useful but not on the critical path.

   Example — backend-security in coding mode: launch a background agent to grep for common vulnerability patterns in newly written code while the main agent finishes implementing the feature.

Write / generate mode — follow the skill's sequential instructions unless background agents are explicitly used for non-blocking analysis.

Ultrathink policy

Skills that require deep analytical reasoning (profiling interpretation, root cause analysis, security auditing) include a Thinking mode: ultrathink instruction in their SKILL.md body. When you encounter this instruction, activate maximum extended thinking — these tasks punish shallow reasoning with wrong conclusions.

When creating or modifying a skill that involves deep analysis, profiling, debugging methodology, or security auditing, or for non-engineering skills that involve synthesis of conflicting sources, competitive analysis, or complex audience/market strategy, add this line in the top-of-body directives block, after Persona (if present) and before the first heading:

**Thinking mode:** Use `ultrathink` for <task description>. <Why deep reasoning matters for this skill>.

Update the README.md Ultrathink column (🧠 emoji) to keep track of skills requiring ultrathink mode.

Tool reference sections

When a skill mentions an important tool (e.g. promql-cli, gh, curl), create a references/ markdown file with a comprehensive reference section listing many command examples. This helps users discover tool capabilities without leaving the skill content.

Example: For the samber/cc-skills@promql-cli skill, create references/usage.md with examples like:

promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output json                            # JSON output
[...]

When the tool has sub-commands, flags, or configuration files, showcase them generously — list every useful sub-command with a realistic example, show flag combinations for common workflows, and include sample config files with inline comments. Developers discover tool capabilities through examples, not by reading --help output.

Link to this reference from the main SKILL.md using relative markdown links.

For content and platform skills (e.g. linkedin-ghostwriting, content-strategy), references/ files serve the same progressive-disclosure purpose but contain writing frameworks, worked examples, editorial checklists, templates, or hook libraries — not command references. The same principle applies: keep SKILL.md focused on essentials and move depth to references/ so it is loaded only when needed.

Progressive disclosure

Skills are structured for efficient context use:

1. Metadata (~100 tokens): name and description are loaded at startup for all skills
2. Instructions (< 5.000 tokens recommended by AgentMD specification): full SKILL.md body loaded when skill activates
3. Instructions (< 2.500 tokens recommended by me): SKILL.md body loaded when skill activates
4. Instructions (< 10.000 tokens recommended by me): full SKILL.md body + secondary files loaded when skill activates
5. Resources (as needed): files in scripts/, references/, assets/ loaded only when required

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

This is a budget. A 100 lines SKILL.md is even better. Feel free to stay below the limits.

Validation

Skill Architecture

Each concept must live in exactly one skill. Skills cross-reference each other instead of duplicating content.

Atomic skills and deduplication

Concept drift between skills creates confusion when the agent loads the wrong one — or two competing ones. Each concept MUST live in exactly one skill (the "owner"). All other skills cross-reference the owner with → See using the fully-qualified owner/repo@skill identifier. When splitting or merging skills, update every cross-reference to the affected skills. Prefer small, focused skills over large monolithic ones.

Company override convention

Some skills are community defaults, not mandates. They include a note at the top of their body that defers to a company skill that explicitly supersedes them.

To override a generic skill, add this line near the top of your company skill's body (replace <skill-name> with the target):

This skill supersedes samber/cc-skills@<skill-name> skill for [company] projects.

The override is skill-specific: your company skill must name each generic skill it supersedes. Plugin-wide override (samber/cc-skills) is not supported — be explicit. The README skills table (Override column) lists which skills support this.

Cross-skill references

Skills use the owner/repo@skill:version identifier format for cross-references. This convention aligns with the skills CLI owner/repo@skill install shorthand and extends it with an optional :version segment for pinning.

Full form: samber/cc-skills@conventional-git:1.2.0 Common form (no version): samber/cc-skills@conventional-git

Always use the fully-qualified owner/repo@skill form in backticks, even for references within the same plugin. This makes every reference portable, searchable, and unambiguous regardless of where the skill is consumed.

Inline: see the samber/cc-skills@conventional-git skill. Arrow-prefixed lists: "→ See samber/cc-skills@conventional-git skill for …"

Install mapping: the identifier maps to skills CLI commands:

• samber/cc-skills@conventional-git → npx skills add samber/cc-skills --skill conventional-git
• samber/cc-skills → npx skills add samber/cc-skills

Writing skills and humanizer

All content-producing skills (linkedin-ghostwriting, press-release-writer, technical-article-writer, substack-ghostwriting) MUST include a humanizer step that invokes a humanizer skill after the draft is written. This ensures AI-generated content is scrubbed of detectable patterns before delivery. When creating new writing or content skills, include a similar humanizer step. The instruction should be generic (not pinned to a specific humanizer skill) so it works with any humanizer available in the user's environment.

Large scope research

When a skill requires broad understanding of a large body of content (e.g. migration, refactoring, architecture review, auditing a content library, multi-channel analysis), it SHOULD recommend using parallel sub-agents (up to 5) via the Agent tool to explore different areas simultaneously. Each sub-agent should target a distinct search scope (e.g. different modules, content sections, channels, or topic areas). This dramatically reduces research time on large codebases and content libraries alike.

Writing Guidelines

When editing skill files, fix grammar mistakes if you find some.

Avoid duplicating well known conventions

Skills should NOT re-explain rules that are already enforced by external tooling or well-documented standards. For engineering skills, if a linter config is present in the skill directory, the linter is the source of truth. For marketing or content skills, if a brand guide, platform style doc, or editorial standard exists, defer to it. Skill instructions should focus on higher-level judgment calls that tools and documents cannot automate — not low-level rules like formatting, naming, or platform-specific constraints that are already codified elsewhere.

Teach reasoning, not only rules

Skills MUST teach Claude how to think about problems, not just list prescriptive rules. Every recommendation needs a "why" — what goes wrong without it, what consequence the reader avoids. Bare imperatives like "NEVER do X" without rationale are not acceptable.

When a recommendation addresses a problem that can be confirmed with a diagnostic tool, add a Diagnose: line indicating which tool(s) to use to validate the hypothesis before applying the fix. This is essential in performance-oriented skills but also useful in any skill where a tool can confirm the root cause. The diagnostic tool must NOT apply the fix automatically (e.g. never use --fix flags) — let the LLM interpret the diagnostic output and perform the improvement itself, so changes are tracked and can include explanatory comments.

Format Diagnose lines with a carriage return before each tool, numbered by importance and potential impact (1-, 2-, 3-, …):

**Diagnose:** 1- `lighthouse --output json` — audit page performance and accessibility; look for scores below 90 2- `curl -I https://example.com` — check response headers for caching and compression 3- Prometheus `rate(http_requests_total[5m])` — track request rate trend in production; compare before/after deploy

Diagnostic tools include CLI commands, runtime introspection, and production monitoring queries (Prometheus PromQL, continuous profiling). Use CLI tools for local investigation and monitoring queries for production trend analysis.

Transformation patterns:

• Best Practices items: embed the tradeoff in one sentence — "Inline styles work for one-offs but break theming consistency when used throughout a component"
• Common Mistakes tables: inject the "because" into the Fix column — "predictable random seeds let attackers reproduce sequences; use a cryptographically secure source instead"
• Code example comments: carry the reasoning — // ✗ Bad — mutating props breaks unidirectional data flow; copy before modifying
• Section intros: add a 1-2 sentence framing paragraph that establishes the mental model before listing specifics

Tool and platform-specific skills

When a skill describes a third-party library, CLI tool, or external platform (e.g. samber/cc-skills@promql-cli, samber/cc-skills@linkedin-ghostwriting), the skill instructions must cover the following depending on the type:

• CLI tools — list commands, flags, and common workflows in a references/ file (see Tool reference sections)
• APIs, libraries, SDKs — list key methods, types, and usage patterns; the model should know what to call without guessing
• Content platforms — enumerate hard constraints: character limits, post/thread size limits, supported formatting, rate limits, and any other non-negotiable rules the agent must respect (e.g. LinkedIn post length, Twitter/X characters per tweet and max thread size)

All three types must include a disclaimer that the skill is not exhaustive and recommend referring to the tool's or platform's official documentation for up-to-date information, since static markdown becomes outdated.

Skills dedicated to a single open-source project (CLI tool, library, SDK) must also include a line at the end of the skill body pointing to the issue tracker for bugs or unexpected behavior:

If you encounter a bug or unexpected behavior in <tool>, open an issue at <repo>/issues.

Important: Skill body text must NEVER contain explicit MCP tool-calling instructions (e.g. "call resolve-library-id", "call query-docs", "use the MCP context7 server"). These trigger prompt-injection detections in security scanners (Snyk). Instead, use generic formulations like:

This skill is not exhaustive. Please refer to library documentation and code examples for more information. Context7 can help as a discoverability platform.

The mcp__context7__* tools may still be listed in allowed-tools frontmatter — only the body instructions are restricted.

Evaluation

Adversarial evaluation design

Run skill evaluation with the pattern recommended by /skill-creator. Use /tmp/{skill-name}-workspace as default workspace for ephemeral files.

Evals MUST be adversarial — they test the skill's unique value, not common knowledge the model already has. A good eval has a "trap" the model falls into without the skill but avoids with it. Every rule of a skill must have its test.

Size evaluations to the skill's Directory (tok) column in README.md: expect ~10 assertions per 1,000 tokens of skill content (full directory excluding evals), with a minimum of 50 assertions. Examples from the current table:

Store your evaluation scenarios in skills/{name}/evals/evals.json.

Design principles:

• Never test common knowledge. If the model passes both with and without the skill, the eval is useless. Avoid testing well-known patterns the model handles correctly without any skill loaded.
• Test the skill's unique guidance. Identify what the skill teaches that the model wouldn't do by default — subtle tradeoffs, non-obvious tool choices, domain-specific gotchas.
• Create traps. Frame the task so the natural/default approach is wrong. The skill should steer toward the correct approach.
• Test judgment, not API knowledge. Ask "which data structure?" not "how to use data structure X?". The model knows APIs; the skill adds architectural judgment. For content skills, the same principle applies: ask "which hook framework fits a counter-intuitive insight for a skeptical B2B audience?" — not "list the available hook frameworks".
• Avoid leading prompts. Don't mention the correct approach in the task description. Don't hint at the answer.
• Stress-test edge cases. The skill's common-mistakes tables and "when NOT to use" guidance are high-value targets.

Anti-patterns to avoid:

• Testing well-known patterns the model already uses by default → eval is trivially easy
• Testing basic API usage (how to call X) instead of judgment (when to use X vs Y)
• Any eval where both with/without score 100% → eval is too easy, redesign it

Evaluation Reporting

Eval results go in EVALUATIONS.md at the repo root. Append new skill sections — never overwrite previous runs. The file is wrapped in <!-- prettier-ignore-start/end --> so Prettier doesn't break the HTML spans.

Structure per skill:

## `skill-name` — vX.Y.Z

Summary table (Overall with/without/delta)

<details>
<summary>Full breakdown (N assertions)</summary>

Metadata line (model, runs, grading method)
Flat table: # | Assertion | With | Without
  - Eval header rows: empty # cell, bold eval name + description, bold score spans
  - Assertion rows: a.b numbering, assertion text, colored ✓/✗ spans
  - Failed cells may include short evidence after ✗ (e.g. "✗ NewStore()")

</details>

Styling: Two CSS classes in the file's <style> block — .g { color: #22863a; font-weight: bold; } (green/pass) and .r { color: #cb2431; font-weight: bold; } (red/fail). Use <span class="g">✓</span> for pass and <span class="r">✗</span> for fail. Eval header scores use the same classes: **<span class="g">4/4</span>** or **<span class="r">2/4</span>** (red when score < max).

Numbering: a.b format — a is the eval number, b is the assertion within that eval (e.g., 4.3, 11.2). Eval header rows leave the # cell empty.

See EVALUATIONS.md for the canonical format.

After updating EVALUATIONS.md sum all the skill reports and update the table in Skill evaluations section of README.md.

Also update the Summary table at the top of EVALUATIONS.md: add a new row for the skill (or update the existing row if re-running), then recompute the Total row by summing all numerators and denominators across all skills. The table is ordered by Delta ascending (low → high). Populate the Concern column using these rules: "Low delta" (≤32pp), "High without" (Without ≥65%), "Low with-skill score" (With ≤90%) — combine when multiple apply. Use bold on Concern values to draw attention. The Uplift column shows With / Without rounded to 2 decimal places and suffixed with × (e.g. 1.64×); recompute it for every row including the Total.

Workflows

Working in worktrees

All implementation work MUST happen in a git worktree in .claude/worktrees/, never directly on the checked-out branch.

Before starting any task, propose a branch name and ask the developer to confirm. Also run git worktree list first — if an existing worktree covers the same skill or a closely related topic, suggest reusing it and let the developer decide.

After updating a skill

After making changes, suggest the following as next steps for the developer to run. Do NOT execute these automatically.

1. Validate against the spec: skills-ref validate ./skills/{name} (disabled — skills-ref doesn't support user-invocable yet)
2. Reformat markdowns with npx prettier --write *.md "**/*.md" then lint with markdownlint-cli2 --config .markdownlint-cli2.jsonc ./ — run before measuring tokens, as formatting changes token counts
3. Measure token counts:
   • Description (tok): awk 'NR==1 && /^---$/{found=1; next} found && /^---$/{exit} found && /^description:/{print}' skills/{name}/SKILL.md | tiktoken-cli
   • SKILL.md (tok): tiktoken-cli skills/{name}/SKILL.md
   • Directory (tok): tiktoken-cli --exclude "evals" skills/{name}/ (exclude evals/ subdirectory)
4. Update the README.md table with the measured token counts, update the total rows, and update the Error rate gap column (Without - With, expressed as a negative percentage, e.g. -39%)
5. Increment metadata.version in the changed SKILL.md and the plugin version in .claude-plugin/plugin.json, .cursor-plugin/plugin.json and gemini-extension.json — all three plugin files MUST have the same version. Also update the Version column for the skill in README.md.
6. Run skill evaluation via /skill-creator: 10+ evals, run them with and without the skill via parallel subagents, grade with LLM-as-judge (no human in the loop), print results, suggest improvements if needed, and append/update the report to EVALUATIONS.md following the format in Evaluation Reporting
7. Depending on evaluation final report, suggest improvements and loop

For initial evaluation of skills, use Human-as-Judge.

Checking for outdated skills

Skills covering a specific library or framework can become stale when the project releases breaking changes or new APIs. Run this check periodically (e.g. monthly) to surface outdated skills.

1. Grep all SKILL.md files for skill-library-version entries to build the inventory.
2. For each skill with a skill-library-version, fetch the latest release from the project's GitHub releases page or changelog via web search.
3. Compare the skill's recorded version against the latest release. Flag skills where the latest version is a higher major or minor than skill-library-version.
4. For flagged skills, skim the changelog between the recorded version and the latest to identify breaking changes or new APIs that the skill should cover.
5. Suggest a skill update for each flagged skill, summarizing the relevant changelog entries.

After updating a skill to reflect a new library version, bump skill-library-version to the new version and follow the After updating a skill checklist.

Plugin Configuration

Plugin metadata is defined in .claude-plugin/plugin.json, .cursor-plugin/plugin.json and gemini-extension.json. Both files MUST have the same version value. Fields include:

• Plugin name, version, and description
• Author and repository information
• Keywords for discoverability

Formats

Write short sentences.

Format 5: Imperative Prose (recommended by skill-creator)

## Writing Rules

Cut ruthlessly — every word must work. Remove filler words like "very", "really", "incredibly". Use active voice. Vary sentence length: 3-5 words for impact, then medium length for explanation.

Format 1: Categorized examples (Good / Bad)

## Static error messages

'''ts // ✓ Good — {tell why} throw new Error("unexpected error")

// ✗ Bad — {tell why} throw "unexpected error" '''

Format 2: Template / Example-Driven

## Commit Message Format

ALWAYS use this exact template:

''' <type>[optional scope]: <description> [optional body] '''

**Example 1:** Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication

**Example 2:** ...

Format 3: Categorized Bullet Lists (Do / Don't / Avoid)

**Formatting:**

- Mobile-first (58% on mobile)
- Never more than 2 visual lines per paragraph on phone
- Line breaks between most sentences

**Avoid:**

- Rhetorical questions
- Empty words ("digital landscape", "incontournable")
- Emoji abuse

Format 4: Numbered RFC-style Rules (MUST/MAY/SHOULD)

## Git conventions

1. Commits MUST be prefixed with a type
2. The type `feat` MUST be used for new features
3. A scope MAY be provided after a type, in parentheses
4. A description MUST immediately follow the colon and space