Universal-Skills

Universal-Skills is a collection of high-leverage "Meta-Skills" designed to upgrade AI Agents from simple chat bots to autonomous engineers.

Unlike standard prompts, these skills are Agent-Agnostic and Architecture-Agnostic. They function as plug-and-play modules that give an agent specific capabilities (e.g., "Review Code like a Sarcastic Senior Engineer", "Generate production-ready MCP servers", "Humanize AI text").

Table of Contents

• Universal-Skills
  • Table of Contents
  • Installation
    • Antigravity (Recommended)
    • Cursor
    • Claude (Projects)
  • Skill Registry
    • Core Meta-Skills
    • Development Skills
    • Content Skills
    • Office Skills
    • Verification Skills (VDD)
    • Agentic Workflows
    • Custom Commands Deployment
  • Licensing
  • Contributing
  • Documentation

Installation

First, clone this repository to your machine:

git clone https://github.com/MatrixFounder/Universal-skills

Then, choose your platform below.

Antigravity (Recommended)

Where skills live

Location	Scope
<workspace-root>/.agent/skills/<skill-folder>/	Workspace-specific (Skills)
<workspace-root>/.agent/workflows/<workflow.md>	Workspace-specific (Workflows)
~/.gemini/antigravity/global_skills/<skill-folder>/	Global (Skills)

Setup

1. Copy the skills folder content into one of the locations above.
2. The agent will automatically index and load the skills.
3. See Antigravity Skills Docs.

Cursor

Where skills live

Skills are automatically loaded from these locations:

Location	Scope
.cursor/skills/	Project-level
.claude/skills/	Project-level (Claude compatibility)
.codex/skills/	Project-level (Codex compatibility)
~/.cursor/skills/	User-level (global)
~/.claude/skills/	User-level (global, Claude compatibility)
~/.codex/skills/	User-level (global, Codex compatibility)

Setup

1. Copy the skills folder content into one of the locations above.
2. Cursor will automatically recognize these as distinct capabilities.
3. See Cursor Skills Docs.

Claude Code

Where skills live

Location	Scope
<workspace-root>/.claude/skills/<skill-folder>/	Workspace-specific (Project)
~/.claude/skills/<skill-folder>/	Global (Personal)

Option A — install one skill at a time as a Claude Code plugin (recommended):

This repo ships a Claude Code plugin marketplace at .claude-plugin/marketplace.json listing each skill as an independently installable plugin. You can pick exactly the skills you need; Claude Code clones the whole repo once and exposes each plugin from there.

# 1. Add the marketplace once.
/plugin marketplace add MatrixFounder/Universal-skills

# 2. Install only the skills you want.
/plugin install docx@universal-skills
/plugin install pdf@universal-skills
/plugin install vdd-adversarial@universal-skills
# ... etc.

# 3. Browse the catalog any time.
/plugin

Available plugins (by category):

Category	Plugins
office	docx, xlsx, pptx, pdf, html2md, marp-slide
meta	skill-creator, skill-validator, skill-enhancer, skill-auto-improve
verification	vdd-adversarial, vdd-sarcastic
content	post-writing, text-humanizer, summarizing-meetings, transcript-fetcher
workflow	brainstorming
development	mcp-builder, hooks-creator

Managing installed plugins:

# Update a single plugin to the latest commit on origin.
/plugin update docx@universal-skills

# Refresh the marketplace catalog after we publish new plugins or update
# descriptions.
/plugin marketplace update universal-skills

# Uninstall when you no longer need a plugin.
/plugin uninstall docx@universal-skills

# Inspect what's installed and from which marketplace.
/plugin list

Plugins land in Claude Code's per-user cache at ~/.claude/plugins/cache/; uninstall removes them cleanly. Install scope defaults to --scope user; pass --scope project to bind a plugin to a specific repo.

Option B — copy the skills folder manually:

1. Copy the skills folder content into one of the locations above.
2. See Claude Code Skills Docs.

Note for marketplace developers: both the per-plugin plugins/<name>/ tree AND .claude-plugin/marketplace.json are generated by bash scripts/sync-plugins.sh. Re-run it after adding/removing/renaming a skill. The script:

• Reads skills/*/SKILL.md to enumerate plugins.
• Symlinks plugins/<name>/skills/<name> → ../../../skills/<name> so the source of truth stays in skills/ (no duplication, no breakage of the byte-identity replication protocol in CLAUDE.md §2).
• Pulls per-plugin description (curated tagline) and keywords from a curated table inside the script — NOT from SKILL.md description:, which is optimized for Claude's skill-routing trigger matching, not for marketplace browsing.
• Runs a drift check at the end: every plugin on disk must appear in the catalog, and every catalog entry's source must resolve. The script exits non-zero if either invariant is violated.
• Only deletes a plugins/<name>/ folder when no corresponding skills/<name>/ exists, so manually-curated plugins outside the skills/-tracked set survive a re-sync.

Skill Registry

Core Meta-Skills

Skill	Description	Tier
Brainstorming	Explores user intent, clarifies requirements, and designs solutions with domain-specific research and self-correction. Use before writing code.	2
Skill Enhancer	A meta-skill to audit, fix, and improve other skills. Enforces "Gold Standard" compliance (TDD, CSO, Script-First). Implements rules from Skill Execution Policy.	2
Skill Creator	Authoritative guidelines for creating NEW skills. Ensures compliant directory structure and philosophy. Implements rules from Skill Execution Policy.	2
Skill Auto-Improve	Vendor-agnostic meta-skill that automatically improves any artifact (skill, prompt, command/workflow, eval dataset) against a measurable metric. An orchestrator runs Proposer + Evaluator subagents in a propose→evaluate→keep/revert loop (immutable eval harness, git-isolated, revertible). Works across Anthropic / OpenAI / Gemini / OpenAI-compatible gateways.	2
Summarizing Meetings	Universal, model-agnostic summarization meta-skill. Summarizes meeting transcripts and documents (articles / papers / threads), auto-detecting the content class. Emits a two-level pyramid Markdown note (default) or opt-in structured note-JSON (--emit note-json) for a knowledge-base / wiki import — with known_concepts reconciliation, verbatim-quote + clean-name discipline, and an explicit no-silent-translation policy. v1.0 meeting→pyramid path is byte-for-byte back-compatible.	2
Wiki Ingest	Hybrid maintenance layer for an Obsidian-style llm-wiki (Karpathy pattern). Four modes: ingest (delegates to Summarizing Meetings, then upserts concept/entity pages additively, attaches [^src-...] footnotes, flags contradictions, updates index.md + log.md), lint (orphans / dangling links / missing pages / open contradictions), reindex (rebuild index.md from disk, preserve custom sections, merge duplicates), query (keyword-find + synthesise with citations). Filesystem-safe (path-traversal guard, Unicode-aware slugs, case-collision detection). Composes with Transcript Fetcher + Summarizing Meetings: fetch → summarize → ingest.	2
Obsidian CLI	Drives the running Obsidian desktop app via the official obsidian CLI (1.12+): link-safe rename/move (app rewrites inbound [[wikilinks]]), typed frontmatter properties, task toggles, daily-note capture, template insertion, Base queries, file-history recovery. Three-tier safety model (T1 read-only / T2 mutating / T3 banned-by-default incl. eval and template-exec surfaces), injection-resistant (note content is data, never commands). Pairs with Wiki Ingest: live-app ops here, wiki layer there, wiki-ingest reindex as the single coherence step after structural changes — see the pairing guide.	2

Development Skills

Skill	Description	Tier
MCP Builder	Comprehensive guide for building Model Context Protocol (MCP) servers in Python or TypeScript. Includes best practices for tool design.	-
Hooks Creator	Generates secure, compliant Gemini CLI hooks (Bash/Node) with automated config and VDD-verified security gates.	2

Content Skills

Skill	Description	Tier
Post Writing	4-step editorial pipeline for LinkedIn/Telegram posts: analyze → hook → draft → review. Includes brand voice guides (RU/EN), 7 hook formulas, platform formatting, and review checklist.	2
Text Humanizer	Rewrites text to remove "AI slop" or generates prompt tailored to specific genres (Wiki, Crypto, etc.).	2
Marp Slide Creator	Creates professional Marp presentation slides with 7 pre-designed themes. Supports image layouts, custom CSS, and "make it look good" requests with automatic theme inference.	2
Transcript Fetcher	Pulls clean plain-text transcripts from video / classroom URLs. Three sources: YouTube + Vimeo (via yt-dlp) and Skool classroom lessons (stdlib HTML scrape; cookies optional — public communities work without auth, private ones accept Netscape cookies.txt). Skool lessons delegate embedded YouTube/Vimeo to those adapters automatically. Manual→auto language fallback ladder (ru → ru-orig → en with quality-flag), rolling-caption dedup with cue-grouping + suffix-prefix splice, anchored >> speaker turns, JSON stat sidecar. Opt-in --with-description emits a <out>.description.md (YAML frontmatter + Markdown body, rendered from ProseMirror for Skool, from yt-dlp info.json for YouTube/Vimeo). Composes with Summarizing Meetings: fetch → summarize.	2

Office Skills

Proprietary — All Rights Reserved. Effective 2026-04-25, the four office skills (docx / xlsx / pptx / pdf) are licensed under their per-skill LICENSE (e.g. skills/docx/LICENSE). Source is available for audit and code review only; any use, execution, copying, modification, or distribution requires prior written permission. For licensing inquiries: kuptsov.sergey@gmail.com. The rest of this repository remains Apache-2.0; see the Licensing section below.

Independent re-implementations of the docx / xlsx / pptx / pdf capability set, built from public specifications (ECMA-376, Microsoft Open Specification Promise, W3C, PDF ISO 32000-2) and open-source libraries. Third-party components keep their original licenses; attribution is preserved in THIRD_PARTY_NOTICES.md and in the per-skill NOTICE files.

Skill	Description	Tier
docx	Create / edit / convert / validate .docx. Markdown ↔ DOCX (with A4 / landscape / custom-margin page geometry — --page-size A4), template fill ({{placeholders}}), accept tracked changes (LibreOffice), unpack/pack OOXML, redlining validator (--compare-to ORIGINAL.docx) catches "editor forgot Track Changes" scenarios.	2
xlsx	CSV → styled .xlsx (bold header, frozen row, auto-filter, leading-zero preservation), force formula recalculation via LibreOffice, scan for #REF!/#DIV/0! errors, attach bar/line/pie charts to a range (xlsx_add_chart.py).	2
pptx	Markdown → PPTX (built-in pptxgenjs renderer with auto-pagination, mermaid diagrams via bundled Cyrillic-capable config, accent stripes — OR --via-marp delegation to marp-slide for editorial polish), pptx2md.py (PPTX → structured Markdown: per-slide sections, GFM tables, sidecar images with sha1-dedup, speaker notes, opt-in per-image --ocr via system tesseract, plus opt-in --ocr-denoise to filter noise from decorative images), outline2pptx.js (heading-only outline → slide skeleton with TODO placeholders), pptx → PDF, slide thumbnail grids, pptx_clean.py to drop orphan slides/media after manual editing.	2
pdf	Markdown → PDF (weasyprint, with optional ```mermaid → PNG via mmdc and bundled Cyrillic-capable `mermaid-config.json`), PDF merge / split (by ranges, per-page, fixed chunks), AcroForm form fill / inspect / flatten (`pdf_fill_form.py`), TOC bookmarks preserved.	2
html2md	Web/HTML → Markdown web-clipper + universal agent step. Input: a live URL or a saved .html/.mhtml/.webarchive. Hybrid Python+Node reusing the docx turndown core + pdf web_clean cleaner (two-master, fork-free). html2md-owned conversion for doc-site SPAs (GitBook/Mintlify/Fern): ARIA-role → GFM tables, chrome/empty-heading tidy, multi-line-link collapse, arXiv/LaTeXML ltx_listing → fenced code, and data:-URI blob stripping. YAML frontmatter, image download (default on, <base href>-aware, sha1-deduped _attachments/, --max-images), dual-output (<slug>.md + .reader.md), --stdout + --json-errors. Lite (httpx+trafilatura) fetch with per-hop SSRF guard + PDF/binary rejection; opt-in Chrome (--with-chrome) for JS pages. Committed regression battery.	2

The three OOXML skills (docx/xlsx/pptx) share an identical scripts/office/ module + _soffice.py LibreOffice wrapper. The docx skill is the MASTER — modifications must follow the strict replication protocol in CONTRIBUTING.md §3.

html2md is the repo's first two-master skill: its turndown core is byte-identical to docx's (html2md_core.js ← docx2md.js) and its web_clean/ HTML-cleaning cluster is byte-identical to pdf's html2pdf_lib/ — both fork-free and diff -q-gated in CI. It therefore joins the proprietary set (derived work embedding docx/pdf code). Same protocol; see CONTRIBUTING.md §3.

Cross-cutting safeguards in the shared office/ module:

• office/_encryption.py — every reader script calls assert_not_encrypted() before opening, so password-protected files AND legacy .doc/.xls/.ppt (CFB containers) fail fast with a clear remediation hint instead of a BadZipFile traceback.
• office/_macros.py — detects .docm/.xlsm/.pptm (vbaProject.bin or macroEnabled content-type); writers warn loudly when the chosen output extension would silently drop the macros at open time. Read-only support: bytes survive through unpack/pack, but Office apps respect the content-type, so renaming an output to a non-macro extension is treated as data loss.
• office/validate.py package-layout allow-list (2026-05-12) — every ZIP entry must live under the canonical OOXML prefix set ([Content_Types].xml, _rels/, word//xl//ppt/, docProps/, customXml/ per ECMA-376 §11.3.10). Non-canonical entries surface as warnings; with --strict, they fail validation (exit 1). Catches scratch-file leaks (e.g. temp files accidentally packed into the container) that Microsoft Word silently refuses to open while LibreOffice tolerates.

Cross-skill helpers (byte-identical at scripts/ level across all four office skills, including pdf):

• _errors.py — --json-errors flag on every Python CLI (including argparse usage errors via a transparent parser.error patch) emits a single-line envelope on stderr: {"v":1,"error":"…","code":N,"type":"…","details":{…}}. The schema version v is always present; bumped only on breaking changes. Domain exits use code≥1; usage errors keep argparse's code=2 with type:"UsageError".
• preview.py — universal INPUT → PNG-grid renderer; takes any of .pdf/.docx/.xlsx/.pptx (incl. .docm/.xlsm/.pptm) and produces a single labelled JPEG. PDF goes straight through Poppler; OOXML routes via LibreOffice → Poppler. Tunable via --soffice-timeout (default 240s, OOXML→PDF) and --pdftoppm-timeout (default 60s, PDF→JPEG); auto-creates the output's parent directory; CLI bounds (--cols ≥1, --dpi ≥1, etc.) validated up-front so bad inputs return an InvalidArgument envelope instead of a Python traceback.

Mermaid diagrams are rendered to PNG by mmdc (@mermaid-js/mermaid-cli v11) inside md2pdf.py, md2pptx.js, and marp-slide. Office skills ship a byte-identical Cyrillic-friendly mermaid-config.json (Arial Unicode MS → Noto Sans → DejaVu Sans fallback chain) and pass it to mmdc by default; override with --mermaid-config PATH or opt out with --no-mermaid-config. The Chromium binary mmdc drives lives in ~/.cache/puppeteer/ (~1 GB, shared user-wide across every skill that uses mmdc) — it's NOT in any per-skill node_modules/.

End-to-end smoke tests (per skill scripts/tests/test_e2e.sh + top-level tests/run_all_e2e.sh) run every user-facing CLI on a real fixture and validate the output. The full suite covers all four skills with 201 assertions (66 docx + 40 xlsx

• 48 pptx + 47 pdf) — including parameterized --json-errors envelope checks for every plumbed CLI, three rounds of VDD adversarial regression guards (false-positive macro detection, parser.error envelope routing, subprocess hygiene), structural-semantic validation (slide/sheet/layout/master chains, shared-string + style index bounds, orphan parts, ECMA-376 ID range rules) backed by 18 unit tests in office/tests/test_{pptx,xlsx}_validator.py, mermaid edge-case fixtures (cyrillic / sequence / gantt / large-mindmap / broken-with- strict), and visual regression (tests/visual/) of every output PDF against a committed first-page golden. A separate hypothesis fuzz suite (tests/property/) black-box-tests md2pdf / md2docx / csv2xlsx for crash-on-edge- input. Together they form the primary regression gate before each release; the office-skills GitHub Actions workflow runs all of the above on every PR.

For practical usage of all four skills — including the complete package inventory (what's installed globally vs per-skill, total disk footprint, cleanup recipes) — see the Office Skills Manual. For the roadmap of upcoming additions and known limitations, see the Office Skills Backlog.

Verification Skills (VDD)

Skill	Description	Tier
VDD Adversarial	Verification-Driven Development. Challenges assumptions, simulates failures, and rejects "happy path" thinking.	2
VDD Sarcastic	The "Sarcasmotron". Same rigor as VDD Adversarial, but with a provocative tone to force the agent/user to defend their logic.	2
Skill Validator	Automated security & compliance scanner for skills. Detects malware, obfuscation, Base64 payloads, and structural violations.	2

Agentic Workflows

Workflow	Description
Auto-Healing Skill	Automated "Doctor" loop. Runs skill-validator to find issues, then activates skill-enhancer to fix them using VDD-verified patterns.

Custom Commands Deployment

To make the Auto-Healing Workflow available as a native command (/auto-heal-external-skill), follow these steps:

Gemini CLI

Create a symlink to the custom command definition:

mkdir -p ~/.gemini/commands
ln -s $(pwd)/custom-commands/auto-heal-external-skill.toml ~/.gemini/commands/auto-heal-external-skill.toml

Usage: /auto-heal-external-skill <path/to/skill>

Claude

Create a symlink to the slash command definition:

mkdir -p ~/.claude/commands
ln -s $(pwd)/commands/auto-heal-external-skill.md ~/.claude/commands/auto-heal-external-skill.md

Usage: /auto-heal-external-skill <path/to/skill>

Licensing

This repository uses a split licensing model:

Scope	License	Source of truth
Repository root and all skills except the proprietary office skills	Apache-2.0	LICENSE
skills/docx/, skills/xlsx/, skills/pptx/, skills/pdf/ (effective 2026-04-25), and skills/html2md/ (derived work embedding docx/pdf code)	Proprietary — All Rights Reserved	skills/docx/LICENSE, skills/xlsx/LICENSE, skills/pptx/LICENSE, skills/pdf/LICENSE, skills/html2md/LICENSE
Third-party components used by any skill (XSD schemas, pip/npm runtime deps, external CLI tools)	Their original licenses, unchanged	THIRD_PARTY_NOTICES.md + per-skill NOTICE

For the office skills (docx / xlsx / pptx / pdf): the source is published for audit, security review, and personal study only. Any use, execution, integration, copying, modification, or redistribution — commercial or non-commercial — requires prior written permission from the copyright holder. Snapshots of these skills that were distributed under Apache-2.0 prior to 2026-04-25 remain available under their original Apache-2.0 terms in the public git history; that grant is not retroactively revoked.

Licensing inquiries: kuptsov.sergey@gmail.com.

Contributing

Before opening a PR or modifying any skill, read docs/CONTRIBUTING.md. It covers:

• Project layout and per-skill structure conventions.
• Universal change checklist (tests, validator, examples, gitignore).
• STRICT Office-skills modification protocol — all changes to scripts/office/ or _soffice.py must be made in the docx master skill and then byte-replicated to xlsx and pptx in the same commit. diff -qr between the three is enforced.
• Adding a new skill via skill-creator.
• Commit hygiene (no node_modules/, .venv/, compiled binaries, ECMA schemas in tree).

Agent-facing rules (development environment behaviours, replication protocol enforcement) live in CLAUDE.md and GEMINI.md, which are kept in sync.

Documentation

Detailed manuals for specific components can be found in docs/Manuals:

• Text Humanizer Manual: Deep dive into the Humanizer's taxonomy and patterns.
• Post Writing Manual: Prompt formulas, IDE/Agent examples, and automated content pipeline architecture.
• Skill Writing Manual: Detailed guide on the philosophy of "Rich Skills".
• Skill Auto-Improve Manual: Guide to the vendor-agnostic auto-improvement meta-skill — the propose → evaluate → keep/revert loop, the six artifact types and their edit formats, the absolute-delta vs debiased pairwise decision rules, text-quality mode (rubric + best-of-N), provider/gateway setup (incl. OpenRouter), the two token-budget axes, the immutability harness, and offline testing.
• Hooks Creator Manual: Guide to generating lifecycle hooks and security blockers.
• Skill Validator Manual: Security auditing guide — CLI reference, architecture, pattern catalog, and CI/CD integration.
• Skill Evals Guide (🇷🇺 RU): Tutorial on how skill evaluations work in skill-creator — the two eval types (trigger vs behavior), LLM-judge vs deterministic script-grader (with a top-level schema of its internals), how to author quality eval sets, when evals go stale, what they affect, and token/effort budgets. Distills advanced practices (reproducibility pinning, set diversification / the "mirage" lesson, A/B isolation, multi-rep) from the wiki-verify reference stand.
• Auto-Healing Workflow: Guide to using the automated repair loop for skills.
• Summarizing Meetings Manual (🇷🇺 RU): Guide to the universal summarization meta-skill — the two axes (transcript vs document × pyramid vs note-JSON), content-class & document-mode detection, the opt-in note-JSON contract (known_concepts reconciliation, verbatim quotes, clean names, neutral title/body fields + --contract wiki alias), the explicit translation policy, templates, tag taxonomy, and Obsidian integration.
• Wiki Ingest Manual: Guide to the llm-wiki maintenance meta-skill — vault layout (_sources/_concepts/_entities), the four modes (ingest/lint/reindex/query), citation pattern ([^src-...] footnotes), contradiction handling, idempotency invariants, the 11 wiki_ops.py subcommands (incl. classify-folder and register-summary), and the fetch → summarize → ingest pipeline.
• Marp Slide Creator Manual: Guide to creating Marp presentations — theme selection, image patterns, CSS customization, and quality checklist.
• Marp CLI Manual: Installation, dependencies, core commands, configuration, and troubleshooting for Marp CLI renderer.
• Office Skills Manual: Practical reference for docx / xlsx / pptx / pdf — install, common workflows, the redlining validator (--compare-to), the LD_PRELOAD AF_UNIX shim for sandboxed deployment, the bundled mermaid config, the test suite (E2E + visual regression + hypothesis fuzz + GHA CI), and a complete package inventory (global vs per-skill vs user-cache).
• html2md Manual: Practical reference for the Web/HTML → Markdown web-clipper — setup, full CLI + exit codes, lite vs Chrome engines, dual-output (whole vs reader), what the converter fixes (ARIA tables, doc-site chrome, split headings, arXiv/LaTeXML listings, data: stripping, image resolution), the SSRF / image-confinement / PDF-guard security model, honest-scope limits, and the two-master replication topology.
• Office Skills Troubleshooting: Symptom → Cause → Fix recipes for the recurring failures — pango/cairo missing, soffice timeout, mmdc fail, AF_UNIX sandbox, encrypted-input rejection, visual-regression drift, ImageMagick v6 vs v7, openpyxl recalc, AcroForm vs XFA.

Project-level guides:

• CONTRIBUTING.md: How to modify skills (universal checklist) and the strict office-skills replication protocol (docx → xlsx/pptx, byte-identical).
• Office Skills Refactoring Plan: Original design rationale for the open-source office skill architecture (historical reference; do not edit, supersede via CONTRIBUTING.md).
• SKILL_EXECUTION_POLICY.md: When to use script-first vs prompt-first, Tier definitions used by skill-validator.