aperio

How to use Aperio's memory tools well — when to recall, what is worth remembering, how to correct a wrong memory, and what must never be stored. Read this when connected to an Aperio MCP server; the tool schemas describe parameters, this describes judgment.

Use this skill to iteratively tune the keywords and descriptions of other SKILL.md files so the skill matcher fires the right skill for a prompt. Runs an autonomous mutate → score → keep/discard loop against a frozen eval set (exam §7 skill triggering), advancing a git branch when match accuracy improves. The eval and scorer are read-only ground truth; the curated keyword frontmatter of other skills is the only editable surface.

Use this skill before writing new code — when the ask is to add a helper, a small feature, a utility, or a new module, and the right amount of code has not been decided yet. Triggers: "write me a helper for…", "add a small feature", "do I need a library for this", "keep it minimal", weighing a new dependency, or any request that could be met by something that already exists. Walk the ladder first: reuse beats stdlib beats platform beats dependency beats new code. This is the pre-write sibling of code-simplification, which cleans up afterwards.

Use this skill when reading from or writing to the persistent memory store. Covers the memory tool API (recall, remember, update_memory, forget) and — for advanced direct access — the SQL schema, vector search patterns, and retrieval priority order against the Aperio Postgres store. Triggers: user states a preference, shares a fact or decision, gives a correction, asks the agent to remember something, or starts a task where past context would affect the output.

Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.

Toolkit for styling artifacts with a theme, and for creating distinctive, production-grade frontend interfaces. Use for: applying pre-set or custom themes to slides, docs, reports, HTML pages; building web components, pages, dashboards, React components, HTML/CSS layouts; or styling/beautifying any web UI with high design quality. ALWAYS use this skill before building any frontend or UI — it prevents the default "clean SaaS with purple gradient" trap that makes every AI-built site look identical.

Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill.

Compact the current conversation into a handoff document a fresh agent can read to continue the work without re-deriving context. Use this when the context window is filling up, when the user says "handoff", "compact", "rotate context", "fresh agent", or "summarize for next session", or before a long-running task is paused. Pairs with `conversation-lifecycle` and `memory-protocol`.

Build polished, responsive, accessible web interfaces and standalone HTML artifacts from plain-language requests. Use when asked to write, display, save, preview, or revise an HTML page or file; for websites, landing pages, dashboards, prototypes, interactive layouts; and for non-coders who need a result they can immediately view and refine visually.

Generate a randomized design brief before any frontend or UI work to prevent aesthetic convergence. Use this skill whenever starting a new website, UI component, dashboard, landing page, or any visual design — especially when the user hasn't specified a visual style. It rolls a design brief (movement, palette, typography, layout, energy) that becomes the binding constraint for the whole build. Also use when the user says designs "always look the same", wants something "unique", "different", or "not like typical AI sites".

Use this skill any time a spreadsheet file (Excel workbook) is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx or .xlsm file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between spreadsheet file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper Excel spreadsheets. The deliverable must be a spreadsheet file (.xlsx). Do NOT trigger when the primary deliverable is a CSV/TSV file, Word document, HTML report, standalone script, database pipeline, or Google Sheets API integration, even if tabular data is involved.

Use this skill when reviewing a change before it merges — a pull request, a diff, or "check my code before I ship it." This is about the review PROCESS: what to look for, how to size a change, how to write useful review comments, and treating approval as a real gate. It is distinct from coding-standards, which defines the naming/style rules themselves; this skill is how a change gets reviewed against them and merged.

Use this skill for complex Word document operations that go beyond simple creation: editing existing .docx files (tracked changes, comments, find-and-replace), inserting or replacing images, custom styles (headings, fonts, page size), footnotes, headers and footers, table of contents, multi-column layouts, numbered lists, bookmarks and hyperlinks, accepting or rejecting revisions, converting .doc to .docx, or when generate_docx is insufficient and a custom docx-js script is needed. Do NOT use for simple document creation — use the docx skill with generate_docx instead.

Use this skill whenever the user wants to create, read, or convert Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce a document, report, memo, letter, summary, or template as a Word file. Also use when reading or extracting content from an existing .docx file, or converting a .docx to PDF. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks. For complex operations on existing documents (tracked changes, comments, XML editing, inserting images, custom styles), use the docx-advanced skill instead.

Use this skill before sending any image to a local llama.cpp vision model (Qwen2.5-VL, LLaVA, Gemma 3, etc.). Triggers when: an image attachment arrives via the web UI, a file path points to a .jpg/.jpeg/.png/.gif/.webp, or a local VLM produces unexpected output on an image (wrong colors, errors, silent failures). This skill normalize the image to RGB PNG at 896×896 with a solid background fill — the format local VLMs expect. Do NOT use for images already confirmed to be plain RGB PNGs with no alpha channel, or when sending images to cloud APIs (Anthropic, OpenAI) that handle raw uploads natively.

This skill defines behavioral rules for tool usage and output hygiene. These apply at all times, for every tool, in every conversation.

This skill defines what to do at the start and end of every conversation — how to apply preloaded memory context, track changes during the session, and surface memory suggestions before closing.

Use this skill when code already works but is harder to read or change than it should be — and the goal is to reduce that complexity without changing behavior. Triggers: "simplify this", "clean up", "this is overcomplicated", reducing nesting or duplication, removing dead code, or cutting an abstraction back to what's actually used. Behavior must stay identical and tests must stay green; this is refactoring for clarity, not a rewrite and not bug-fixing.

Use this skill when something is broken and the cause is unknown — a crash, an exception, a failing test, a wrong result, or "it worked yesterday." Triggers: debugging a bug, reading a stack trace, an unhandled exception, code that is not working or producing wrong output, or an agent that has tried the same fix twice and is looping. This skill is about FINDING the cause systematically, not about writing new features.

Use this skill when a task is complex, multi-step, or ambiguous and the agent needs to think before acting — not just format output. Triggers: problems with unclear requirements, tasks with dependencies or sequencing, situations where acting immediately risks doing the wrong thing, or any task where "plan first, execute second" is safer than jumping in.

Use this skill when writing or reviewing code that handles untrusted input, authentication, secrets, database queries, file paths, or network requests — anywhere a mistake becomes a vulnerability. Triggers: adding auth or permissions, building an API route or MCP tool, touching the db/ layer, handling user input or file uploads, managing secrets and credentials, or an explicit ask to secure / harden / audit something. Aperio is a Node server that stores user memories and exposes tools — treat security as part of writing the code, not a later pass.

Use this skill when writing or changing code whose correctness matters and you want proof it works — not a claim that it works. Triggers: implementing a function or feature where you can write a test first, adding a regression test for a bug, or any time you are tempted to say "it works" without evidence. The core move is RED → GREEN → REFACTOR: write a failing test, make it pass, then clean up. This is the methodology; webapp-testing and run_tests are the tools.

Use this skill when finding, outlining, or quoting content in the user's indexed document folders — notes, write-ups, reports, Markdown, plain text, HTML, PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and email (.eml) — but NOT code. Prefer the document graph (passage search, section outlines, text slices) over full-file reads and wide greps — it is cheaper and more precise. Covers when to reach for which tool and the canonical lookup sequence.

Use this skill whenever writing, reviewing, or modifying any code in any programming language. Enforces universal principles first, then applies language-specific naming conventions. Detect language from context (file extension, user statement, existing code). If ambiguous, ask before writing significant code. Includes annotated good/bad examples per language.

Internal reference for Aperio's automatic PDF preprocessing. Describes the result types (text/scanned/mixed/empty) the MCP attachment router returns when a PDF is uploaded, and how the agent should handle each type. Load this skill when the router has already pre-processed a PDF and you need to know what the result type means and what to do next. Do NOT use for user-requested PDF tasks (creation, merging, splitting, forms, extraction on demand) — use the pdf skill for those.

Use this skill when designing or executing a multi-step tool chain where one tool's output feeds another, or when a tool call might fail and you need a structured recovery strategy. Triggers: chaining two or more tools in sequence, choosing between tools that produce incompatible output shapes, handling retries with backoff, or mapping validation checkpoints across a chain before executing.

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Internal dev skill — use only when explicitly asked to run Playwright browser tests or automation against a local web app (including Aperio's own UI). Triggers on: 'run playwright', 'browser test', 'automate the UI', 'screenshot the app', 'test the frontend'. Do NOT trigger for general user questions about testing strategy or non-browser testing.

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

Use this skill when navigating, understanding, or changing code in an indexed repo. Prefer the code graph (symbol search, source slices, call graph) over full-file reads and wide greps — it is cheaper and more precise. Covers when to reach for which tool and the canonical lookup sequence.

Use this skill when editing non-code files: Markdown, DOCX, PDF, YAML, JSON, TOML, plaintext, or any other document format. Covers surgical editing principles that don't apply cleanly through coding-standards alone. Matched by file extension when the target isn't a code file.

Defines how to use wiki tools (wiki_get, wiki_write) and — critically — how to surface wiki usage to the user. Load whenever you read, write, or might benefit from an article.

Use this skill when a user provides a vague, rough, or underdeveloped idea and wants it turned into a clear, structured, actionable prompt or plan. Triggers: "help me structure this", "I have an idea but don't know where to start", "make this into a proper prompt", or any half-formed concept needing decomposition.