# AGENTS.md: OKHP3/skillz

This is the canonical agent guide and routing index for this repository. Read it before working here. `CLAUDE.md` is a compatibility pointer to this file.

## Project identity

- **Suite:** OverKill Hill
- **Repository:** `OKHP3/skillz`
- **Type:** Public Agent Skills distribution library, using the `SKILL.md` format
- **License:** MIT at the repository level; individual skills may declare a different license in frontmatter
- **Release state:** Unreleased. There are no Git tags.
- **Current inventory:** 283 distribution skills in 19 active families, and 46 project-local support skills under `.agents/skills/`
- **Source of truth:** GitHub repository for installable files; the public landing surface is OverKill Hill `/projects/skillz/`

### Mission: confirmed

Package recurring methods as portable, agent-readable delegation contracts that can run across compatible agent runtimes without repeating the same human explanation.

### Vision: inferred

Become the reusable execution layer of the OKHP3 Visual Language Stack, with composable skill families that make recurring work portable and durable.

## Scope and boundaries

This repository contains SKILL.md contracts, references, examples, fixtures, and small validation or rendering utilities. It also contains the `artifacts/forge/` Vite/React frontend that builds the public Skillz Forge catalog, alongside the Review Desk, API server, and Mockup Sandbox artifacts. It is a pnpm workspace; use the artifact and package-local commands documented below. There is one Git repository at the root; no nested Git repositories were found.

The root family directories are the distribution surface. `.agents/skills/` is a project-local support surface containing cataloging, skill-authoring, FoundRy tooling, and platform-specific context-extraction support. Do not count its packages as additional distribution skills or families.

Do not add employer-specific confidential material, private credentials, tokens, cookies, customer or employee data, proprietary system names, hidden network calls, or destructive behavior. Public skills must use synthetic or public-safe examples. A skill must not instruct an agent to bypass permissions, conceal actions, or remove user consent.

## Repository map

| Path | Role |
|---|---|
| `abrahamic/` | Scripture lookup, observance calendar, tradition reference, and cross-tradition comparison skills |
| `community/` | Imported or community-oriented general-purpose skills, including UI, MCP, social, and authoring guidance |
| `lifetrkr/` | Celestial-data and daily-oracle skills |
| `social-posting/` | Platform-specific drafting contracts for LinkedIn, Facebook, X/Twitter, Discord, YouTube, Ko-fi, Instagram, TikTok, Reddit, Patreon, Pinterest, Slack, Teams, and Telegram |
| `mermaid/` | Mermaid diagram authoring, governance, theming, publishing, updating, and repair |
| `notion/` | AI conversation capture and routing into Notion knowledge structures |
| `knowledge-operations/` | Portable lifecycle for capturing, classifying, researching, validating, and promoting information or exploratory work |
| `language-mediation/` | Controlled transformations across languages, locales, specialist registers, and plain-language audiences |
| `process-capture/` | Process-analysis and documentation pipeline plus the recurring-task capture skill |
| `refolddec/` | ReFolDec fold, unfold, and refold transformations |
| `agent-foundry/` | AI-agent creation, readiness, platform comparison, portability, and lifecycle skills |
| `copilot/` | Host-oriented Agent Skills for GitHub Copilot, Copilot Cowork, SharePoint Copilot, Copilot Studio, and verified Copilot runtimes |
| `universal/` | Cross-project builders, repository organization, cataloging, database cartography, API proxy, OAuth, and deployment skills |
| `context-extraction/` | Source-agnostic and platform-specific AI-thread extraction, project migration, provenance preservation, and handoff skills |
| `outcome-modeling/` | Shared event-to-state forecasting core plus sports, NFL fantasy, business-sales, and prediction-market decision adapters |
| `software-reclamation/` | Remastered software-reclamation workflow for reclaiming undocumented applications, documenting behavior, planning modernization, and handing off support or replacement |
| `glee-fully/` | Glee-fully Tool and Tool-ette skill architecture, Persona Density, hierarchy, and future consumer-skill conversions |
| `askjamie/` | AskJamie-specific Custom GPT creation skills and future professional-support capabilities |
| `.agents/skills/` | Local support skills and the bundled catalog/authoring utilities |
| `docs/` | Stack position, public surfaces, publishing, security, backlog, changelog, and technology inventory |
| `.github/` | Dependabot, runtime pins, and scheduled technology-inventory automation |
| `skillz.manifest.json` | Machine-readable repository metadata synchronized to the current 258-skill distribution inventory |

## Routing index

Load the narrowest matching skill. If several apply, load the foundation or upstream skill first, then the domain or downstream skill. The skill's own `SKILL.md` is the authority for detailed instructions.

### Mermaid family: load `okhp3-mermaid-core` first for every Mermaid task

| Skill | Trigger and loading rule |
|---|---|
| `okhp3-mermaid-core` | Any Mermaid authoring, explanation, validation, or diagram task. Owns audience declaration, diagram-type selection, design system, naming, registry, and validation gates. |
| `okhp3-mermaid-bpmn` | Business process, workflow, approval chain, swim lane, gateway, event, task, subprocess, or BPMN-flavored diagram. Load after core. |
| `okhp3-mermaid-architecture` | C4, system or solution architecture, infrastructure, deployment, service topology, packet, protocol, or integration diagram. Load after core. |
| `okhp3-mermaid-data` | ERD, class diagram, schema documentation, data model, object structure, or relationship diagram. Load after core. |
| `okhp3-mermaid-publish` | Render, export, or publish a finished Mermaid diagram locally or through an approved Mermaid Chart integration. Load after core and validation. |
| `okhp3-mermaid-update` | Change content in an existing working `.mmd` file or Mermaid block while preserving style, class definitions, and init configuration. Load after core. |
| `okhp3-mermaid-repair` | Repair a parse failure or malformed Mermaid render with the minimum syntax change. Load after core. Do not use for intentional content changes. |
| `okhp3-mermaid-theme-builder` | Apply or generate a palette, theme, renderer profile, classDef bundle, or renderer-safe Mermaid styling. Load after core. |
| `okhp3-mermaid-governance` | Declare a project diagram standard, check conformance, or audit cross-diagram style and behavior drift. Load after core. |

Mermaid cross-cutting rules: preserve style during updates, repair syntax minimally, keep source local unless the user authorizes publication, use stable short IDs, quote labels with spaces or special characters, avoid semicolons, and never invent classDef names or renderer capabilities.

### Social posting family

| Skill | Trigger and loading rule |
|---|---|
| `okhp3-linkedin-angles` | Mine a finished artifact or conversation for 3 to 5 LinkedIn-postable angles. It produces candidates and does not draft the post. |
| `okhp3-linkedin-post` | Draft a LinkedIn post from a selected angle or directly named topic. It applies voice and runs the final employer-context scrub. |
| `okhp3-linkedin-voice` | Final filter for any LinkedIn-bound draft, whether generated by this family or written by hand. It is not a generator. |
| `okhp3-linkedin-comment` | Draft a context-aware LinkedIn comment or reply. Load after reading the target post or parent comment. |
| `okhp3-facebook-post` | Draft a Facebook profile, Page, group, or event post after the destination and audience are explicit. |
| `okhp3-facebook-comment` | Draft a Facebook comment or reply after reading the target conversation and identifying its surface. |
| `okhp3-twitter-post` | Draft an X, formerly Twitter, post. `twitter` is the stable package slug; use the standard post constraint unless longer-post eligibility is explicitly established. |
| `okhp3-twitter-comment` | Draft an X reply, called a comment in this family, from supplied parent-post context. |
| `okhp3-discord-post` | Draft a new Discord message, forum post, or thread opener for a named server destination. |
| `okhp3-discord-comment` | Draft a Discord reply to an existing message, thread, or forum conversation. |
| `okhp3-youtube-video` | Draft a YouTube video metadata bundle, optional chapters, and account-side setting handoff from supplied facts. |
| `okhp3-youtube-community-post` | Draft a YouTube channel post or a supplied creator Community contribution, keeping their destinations separate. |
| `okhp3-youtube-comment` | Draft a YouTube comment or reply after reading the supplied video, post, and parent-comment context. |
| `okhp3-kofi-post` | Draft a Ko-fi content post after the post form and intended public or supporter-access audience are explicit. |
| `okhp3-kofi-supporter-reply` | Draft a privacy-preserving reply to a supplied, redacted Ko-fi supporter message. |
| `okhp3-instagram-post` | Draft an Instagram feed post, carousel, Reel, or Story brief after the supplied media form and audience are explicit. |
| `okhp3-instagram-comment` | Draft a context-aware Instagram comment or reply from a supplied post and conversation. |
| `okhp3-tiktok-post` | Draft a TikTok video or photo-post brief from supplied media and source facts. |
| `okhp3-tiktok-comment` | Draft a grounded TikTok comment or reply from supplied post context. |
| `okhp3-reddit-post` | Draft a Reddit submission after the named community, post form, and supplied rules are explicit. |
| `okhp3-reddit-comment` | Draft a Reddit comment or nested reply from supplied thread and community-rule context. |
| `okhp3-patreon-post` | Draft a Patreon post only after its intended public, free-member, or paid-member access boundary is supplied. |
| `okhp3-patreon-comment` | Draft a privacy-preserving Patreon comment or reply from supplied post and access context. |
| `okhp3-pinterest-pin` | Draft a Pinterest Pin title, description, destination-link note, and board handoff from supplied material. |
| `okhp3-pinterest-comment` | Draft a Pinterest comment or reply from a supplied Pin and conversation. |
| `okhp3-slack-channel-message` | Draft a new Slack channel message for a named workspace destination; broad pings need exact approval. |
| `okhp3-slack-thread-reply` | Draft a reply that remains in a supplied Slack parent thread without turning it into a channel broadcast. |
| `okhp3-teams-channel-post` | Draft a new Microsoft Teams channel post for a supplied team, channel, and layout, without assuming posting permissions. |
| `okhp3-teams-thread-reply` | Draft a Microsoft Teams reply within a supplied channel conversation. |
| `okhp3-telegram-channel-post` | Draft a Telegram broadcast-channel post from supplied destination and material context. |
| `okhp3-telegram-group-reply` | Draft a Telegram group or topic reply from supplied parent-message context. |

Social-posting cross-cutting rules: identify acting account, destination, audience, and whether the task is a new post or a response before drafting. Prepare text only; do not publish, schedule, join communities, change settings, or automate engagement without explicit approval. Verify consequential public claims and exclude employer or private context by default. LinkedIn retains its voice and public-context scrub path; Discord requires channel and ping context; Facebook requires surface and audience context; X should not assume Premium capability; YouTube must distinguish video, channel-post, Community, and comment surfaces; Ko-fi and Patreon must treat access boundaries and supporter or member details as private; Reddit requires supplied community rules; Pinterest needs asset, board, and link context; and Slack, Teams, and Telegram require the exact message surface and parent thread when replying. Packages carry no fixed account, person, topic, or viewpoint and obtain their minimum necessary context only at runtime.

### Process-capture family

Use `okhp3-process-intake-and-scope` for a new process, then compose downstream skills as the artifact matures. Use `okhp3-recurring-task-capture` for the meta-task of recognizing a recurring workflow and capturing it as backlog or a new skill skeleton.

| Skill | Trigger |
|---|---|
| `okhp3-recurring-task-capture` | The user says they keep doing something, it is the second or third repetition, or asks to make a workflow into a skill. |
| `okhp3-process-intake-and-scope` | Document or scope a process from scratch, including boundaries, inputs, outputs, and business rules. |
| `okhp3-as-is-process-capture` | Capture and normalize the current running process before redesign or gap analysis. |
| `okhp3-elicitation-interviews` | Prepare interviews, workshops, question plans, or targeted follow-up to fill process gaps. |
| `okhp3-stakeholder-and-role-mapping` | Identify affected parties, influence, interest, engagement, or RACI-ready roles from a process intake. |
| `okhp3-process-narrative-authoring` | Turn a completed intake and stakeholder register into a Process Narrative Specification. |
| `okhp3-visual-process-modeling` | Turn a PNS or process notes into a Mermaid-native bpmn-beta diagram, or validate and repair one. |
| `okhp3-decision-model-authoring` | Convert three or more meaningful gateway decisions or explicit business rules into a DMN-aligned decision model. |
| `okhp3-process-gap-exception-analysis` | Find deviations, missing steps, breakdowns, and undefined exception paths between current and intended process. |
| `okhp3-future-state-change-strategy` | Design a target-state process and change strategy from a gap analysis. |
| `okhp3-process-measures-controls` | Define KPIs, targets, measures, compliance controls, or governance registers for a validated process narrative. |
| `okhp3-raci-governance-matrix` | Generate a RACI or governance responsibility document from a validated PNS. |
| `okhp3-sipoc-generation` | Produce a Suppliers, Inputs, Process, Outputs, Customers summary from a validated PNS. |
| `okhp3-sop-work-instructions` | Produce an SOP or role-specific work instructions from a validated PNS. |
| `okhp3-process-validation-scoring` | Run the V1 to V9 validation suite, quality scoring, and publication gate for a complete process documentation set. |
| `okhp3-publication-handoff-packaging` | Package validated process artifacts for publication or handoff; requires a passing validation report. |

### Notion and ReFolDec families

| Skill | Trigger and loading rule |
|---|---|
| `okhp3-notion-capture-router` | Capture ChatGPT, Claude, Perplexity, Copilot, Gemini, PDF, or pasted AI conversations into Notion structures, dedupe them, split extracts, and reconcile against OKHP3 GitHub. This is not generic note-taking. |
| `okhp3-refolddec-core` | Explicitly transform an artifact between representations, such as idea to diagram, diagram to documentation, documentation to SKILL.md, or unfold/refold with semantic-loss tracking. Load the target domain skill alongside it. |

### Knowledge-operations family

The `knowledge-operations/` family governs destination-neutral lifecycle work
around information and exploratory efforts. It is separate from the
community-originated packages and may evolve independently.

| Skill | Trigger |
|---|---|
| `okhp3-artifact-validation` | Validate a named project change, draft, research packet, skill, promotion package, or handoff before reliance or handoff. |
| `okhp3-capture-intake` | Preserve one raw idea, file, link, transcript, or request before interpretation or triage. |
| `okhp3-evidence-standard` | Classify consequential claims as confirmed, inferred, proposal, or unknown with traceable evidence. |
| `okhp3-graduation-gate` | Decide whether an exploratory effort is ready for formalization, should remain active, should archive, or is blocked. |
| `okhp3-project-promotion` | Prepare an owner-approved formalization packet after a documented graduation decision. |
| `okhp3-source-backed-research` | Produce research or recommendations with traceable sources, retrieval dates, and explicit uncertainty. |
| `okhp3-triage-and-file` | Assign recorded lifecycle dispositions to captured project inbox items without unapproved moves or deletion. |

### Context-extraction family

The `context-extraction/` family contains ten distribution skills for extracting durable, actionable context from manually supplied AI conversations, creating continuation records, and migrating ChatGPT project material. Load the narrowest platform adapter first when one exists, then the shared extraction contract or migration skill, then the downstream destination or artifact skill.

| Skill | Trigger |
|---|---|
| `okhp3-thread-context-extraction` | Cross-platform or unknown-source AI thread extraction with provenance and semantic-loss controls. |
| `okhp3-session-handoff` | Create a durable continuation record when work pauses or crosses a session, machine, or agent host. |
| `okhp3-thread-extract-chatgpt` | Manually supplied ChatGPT chats, Projects, Canvas, Deep Research, or export excerpts. |
| `okhp3-thread-extract-claude` | Manually supplied Claude chats, Projects, Artifacts, Research, or export excerpts. |
| `okhp3-thread-extract-copilot-m365` | Manually supplied Microsoft Copilot or Microsoft 365 Copilot captures. |
| `okhp3-thread-extract-gemini` | Manually supplied Gemini chats, Canvas, Deep Research, or Workspace-grounded captures. |
| `okhp3-thread-context-extraction-grok` | Manually supplied Grok or X-grounded captures. |
| `okhp3-thread-extract-mistral-vibe` | Manually supplied Mistral Vibe or former Le Chat captures. |
| `okhp3-thread-extract-perplexity` | Manually supplied Perplexity threads, Research, or source-rich captures. |
| `okhp3-chatgpt-project-migration` | ChatGPT project migration, lossless archives, provenance ledgers, and repository reconciliation. |

### Abrahamic family

| Skill | Trigger |
|---|---|
| `okhp3-cross-tradition-compare` | Compare parallel teachings or passages across Judaism, Christianity, and Islam, including neutral interfaith displays. |
| `okhp3-tradition-observance-calendar` | Retrieve, compute, or format Jewish, Christian, or Islamic observances, including unified lists and `.ics` output. |
| `okhp3-tradition-reference` | Answer or support canon, denomination, translation, API, and in-scope tradition questions. Read before making tradition-related fetch or scope decisions. |
| `okhp3-verse-lookup` | Route, fetch, normalize, or troubleshoot Bible, Quran, Torah, psalm, or other in-scope scripture passages through public APIs. |

### LifeTrkr family

| Skill | Trigger |
|---|---|
| `okhp3-celestial-data` | Calculate moon phase, illumination, next phase, zodiac season, or Mercury retrograde locally without network access. |
| `okhp3-daily-oracle` | Build a cached daily reading, affirmation, horoscope, tarot, or AI-synthesized daily insight feature. |

### Community family

These are general-purpose or imported skills. Prefer the narrower OKHP3 family skill when both match.

| Skill | Trigger |
|---|---|
| `ai-social-media-content` | Create social content, images, video, reels, shorts, captions, hashtags, or thumbnails. |
| `architecture-decision-records` | Create, review, or maintain ADRs and technical decision records. |
| `brand-guidelines` | Apply Anthropic brand colors, typography, or visual standards. |
| `find-skills` | Discover, evaluate, or recommend an installable specialized skill. |
| `frontend-design` | Build or improve distinctive web UI, pages, components, artifacts, or applications. |
| `mcp-builder` | Build MCP servers or tool integrations in Python, Node, or TypeScript. |
| `mermaid-diagrams` | General Mermaid diagrams when the OKHP3 Mermaid family is not the intended specialized workflow. |
| `skill-creator` | Create, edit, evaluate, benchmark, or optimize a skill. |
| `theme-factory` | Apply or create a reusable theme for slides, documents, reports, HTML, or other artifacts. |
| `vercel-react-best-practices` | Write, review, or refactor React or Next.js for performance. Its nested `agents.md` is package-scoped guidance. |
| `vercel-react-native-skills` | Write, review, or refactor React Native or Expo for performance. Its nested `agents.md` is package-scoped guidance. |
| `web-artifacts-builder` | Build complex multi-component HTML artifacts using React, Tailwind, shadcn, and related frontend tooling. |
| `web-design-guidelines` | Audit UI code for interface, accessibility, UX, or design-guideline compliance. |

### Agent-foundry family

| Skill | Trigger |
|---|---|
| `okhp3-custom-gpt-builder` | Create, audit, test, improve, compare, document, or package a Custom GPT or related reusable AI workflow. Verify current platform facts before stating them as definitive. |
| `okhp3-custom-gpt-readiness` | Assess an incomplete Custom GPT concept, inventory evidence, identify blockers and gaps, and prepare a builder handoff. |
| `okhp3-gpt-skill-conversion-plan` | Assess an existing Custom GPT for conversion into a portable Agent Skill, map semantic coverage and loss, and prepare a Skill Foundry handoff. |

The family is intended to expand to Gemini Gems, Copilot declarative agents, OpenClaw agents, and other agent runtimes when their creation or lifecycle methods become concrete skills.

### Copilot family

The `copilot/` family is the host-oriented distribution surface for
task-focused Agent Skills targeting Copilot-branded runtimes. It keeps GitHub
Copilot, Copilot Cowork, SharePoint Copilot, Copilot Studio, and future verified
Copilot hosts in one catalog family while requiring each skill to declare its
exact host, packaging, capability, permission, and evidence boundary.

Use the host token in the package name, such as `github`, `cowork`,
`sharepoint`, `copilot-studio`, `scout`, or `crosshost`. Do not infer support
for one Copilot surface from support on another. Use `agent-foundry/` for the
creation or migration of an entire Copilot agent; use `copilot/` for the
task-focused skill layer.

### Glee-fully family

| Skill | Trigger |
|---|---|
| `okhp3-glee-fully-foundry` | Design, author, audit, or canon-seal a Glee-fully Tool or Tool-ette Agent Skill. It governs hierarchy, Persona Density, Twig `Best for` boundaries, sibling awareness, leaf logic, and release readiness. |

The Glee-fully Foundry skill is the family-level authoring layer. Converted
consumer Tools and Tool-ettes should be added only after the inventory and
clustering work described in `glee-fully/README.md`.

### Outcome-modeling family

Load `okhp3-outcome-modeling-core` first for any outcome-modeling task, then add the narrowest domain adapter. The family separates calibrated prediction from the economic or constrained decision objective. Its current evaluation status is analytical structural integrity with live performance evidence not run.

| Skill | Trigger and loading rule |
|---|---|
| `okhp3-outcome-modeling-core` | Design or review a multi-scale event-to-state model, feature-compression test, calibrated forecast, objective function, or constrained allocation. Load first. |
| `okhp3-outcome-modeling-sports` | Team, game, player, matchup, season, schedule, roster-event, or sports projection work. Load after core. |
| `okhp3-nfl-fantasy-picks` | NFL fantasy, DFS, salary-cap, waiver, or trade decisions involving replacement value, scarcity, floor, ceiling, and roster constraints. Load core and sports first. |
| `okhp3-outcome-modeling-sales` | Pipeline, salesperson, account, territory, quota, discount, retention, margin, or commercial allocation work. Load after core. |
| `okhp3-outcome-modeling-markets` | Prediction-market probabilities, market-implied prices, resolution rules, liquidity, expected value, or paper backtesting. Load after core; it does not execute trades. |

### Software Reclamation family

Load `okhp3-reclamation-scope` first for any reclamation task, then preserve
evidence with `okhp3-reclamation-intake` and select the narrowest downstream
package. These are remastered OKHP3 editions, not renamed community clones.
They are candidate packages with analytical evidence; do not infer live-system,
production-readiness, legal, or behavioral-uplift claims from their presence.

| Skill | Trigger |
|---|---|
| `okhp3-reclamation-scope` | Establish authority, target identity, data boundaries, technique modes, approvals, and stop conditions. |
| `okhp3-reclamation-intake` | Preserve and inventory source, deployment, runtime, configuration, and business artifacts with provenance. |
| `okhp3-reclamation-platform` | Fingerprint framework, runtime, dependencies, hosting, database, and deployment evidence. |
| `okhp3-reclamation-code-archaeology` | Reconstruct code structure, dependencies, control flow, and application boundaries. |
| `okhp3-reclamation-runtime-reconcile` | Reconcile source, configuration, deployment, observability, and runtime evidence. |
| `okhp3-reclamation-rbac-tracing` | Trace authentication, authorization, roles, permissions, tenancy, and protected actions. |
| `okhp3-reclamation-transaction-flow` | Model vendor, customer, purchase-order, invoice, quotation, document, status, and partner flows. |
| `okhp3-reclamation-security-review` | Run an authorized evidence-led security review distinct from penetration testing. |
| `okhp3-reclamation-char-tests` | Generate safe characterization tests and regression baselines from observed behavior. |
| `okhp3-reclamation-technical-docs` | Produce evidence-led architecture, operations, code-tour, data, and findings documentation. |
| `okhp3-reclamation-target-design` | Design a secure modernization target without prematurely implementing it. |
| `okhp3-reclamation-replacement-spec` | Turn reclaimed evidence into traceable replacement requirements and acceptance criteria. |
| `okhp3-reclamation-migration-cutover` | Plan reversible data, integration, rollback, and cutover stages. |
| `okhp3-reclamation-replacement-build` | Implement an approved replacement in small, testable increments with secure defaults. |
| `okhp3-reclamation-validation-handoff` | Validate and hand off documentation, tests, risks, and support or replacement next actions. |

### Universal family

| Skill | Trigger |
|---|---|
| `okhp3-cloudflare-worker-api-proxy` | Keep an API key server-side while proxying calls from a static frontend through a Cloudflare Worker. |
| `okhp3-brand-style-registry` | Extract named, evidence-backed visual style profiles from approved sources and apply one primary profile with explicitly scoped supporting profiles to SPAs and other artifacts. |
| `okhp3-database-cartographer` | Reverse-engineer a live SQL database into a schema inventory, severity-classified diff, and Mermaid ER handoff without writing to the target. |
| `okhp3-equilibrium-review` | Evaluate documents, reports, spreadsheets, hypotheses, decision memos, or Agent Skills with independent evidence review, conditional disruption, and evidence-based adjudication. |
| `okhp3-foundry-repo-creator` | Convert a GPT, Gem, Copilot agent, prompt bundle, Notion concept, or prototype into a governed FoundRy child repository. |
| `okhp3-google-gis-client-auth` | Implement client-only Google Identity Services OAuth for a static React SPA with Calendar or Tasks access. |
| `okhp3-i18n-page-sync` | Detect which pages on a static site are missing a translation or have drifted from a changed English source, by reusing the site's own search index as the page inventory. Reports drift and names the exact-pair translation skill for each flagged route; never translates or writes a page itself. |
| `okhp3-repository-janitor` | Reconcile local Git mirrors against GitHub, preserve local variations, review branch lifecycle, and prepare safe merge or pruning actions. |
| `okhp3-repository-organizer` | Profile and safely reorganize content-first Git repositories containing mixed knowledge, prompt, document, research, and media assets, with cross-platform naming safeguards. |
| `okhp3-skill-cataloger` | Catalog local `.agents/skills/` or run full-index mode over root family directories. Use the script below and do not hand-edit generated catalog sections. |
| `okhp3-skill-discovery` | Find, verify, compare, and route to currently available project-local, installed, runtime, or plugin-provided skills. |
| `okhp3-skill-foundry` | Create, hone, evaluate, benchmark, brand, or polish a production-quality Agent Skill using the eight-phase Foundry method, evidence ledger, conditional dissent review, and enforced current-state evidence integrity for material releases. |
| `okhp3-skill-promotion` | Promote and synchronize a project-local skill into a verified `skills/` publication mirror and a reviewable canonical `skillz` handoff without blind overwrites or autonomous publication. |
| `okhp3-vite-github-pages` | Deploy or repair a React or Vue Vite SPA on GitHub Pages, especially base path, router, and gh-pages issues. |

### Language-mediation family

Language-mediation packages keep specialist-register mediation separate from
regional-language translation. When both are needed, run them in series:
specialist source locale to plainspoken source locale first, then plainspoken
source locale to target locale. Do not collapse or parallelize the two stages.

| Skill | Trigger |
|---|---|
| `okhp3-translation-en-us-de-de` | Translate an owned plainspoken `en-US` text artifact to `de-DE`. Load only after any specialist source has a completed plain-en-US mediation record. It does not perform medical, legal, engineering, or other register simplification, and it does not cover `de-AT` or `de-CH`. |
| `okhp3-translation-en-us-en-uk` | Adapt an owned plainspoken `en-US` text artifact to British English (`en-GB`) spelling, vocabulary, and locale conventions. A same-language regional adaptation, not a bilingual translation. Does not cover `en-AU`, `en-CA`, or `en-IE`. |
| `okhp3-translation-en-us-es-es` | Translate an owned plainspoken `en-US` text artifact to `es-ES`. Load only after any specialist source has a completed plain-en-US mediation record. It does not perform medical, legal, engineering, or other register simplification, and it does not cover `es-419`, `es-MX`, or `es-US`. |
| `okhp3-translation-en-us-es-mx` | Translate an owned plainspoken `en-US` text artifact to Mexican Spanish (`es-MX`). Load only after any specialist source has a completed plain-en-US mediation record. Does not cover `es-ES` or `es-419`. |
| `okhp3-translation-en-us-fr-fr` | Translate an owned plainspoken `en-US` text artifact to `fr-FR`. Load only after any specialist source has a completed plain-en-US mediation record. It does not perform medical, legal, engineering, or other register simplification. |

### Project-local support skills

`.agents/skills/` contains 46 project-local support skill packages, cataloged in `.agents/skills/README.md`. The operator guide for the repository validators lives in `.agents/skills/VALIDATION.md`. These packages support this project and overlap with some distribution packages. Use the local copy when the task is specifically about this repository's catalog or authoring workflow.

## Technology and runtime

- Markdown, JSON, YAML, Mermaid, and SKILL.md are the primary artifact formats.
- Node.js runs the 15 process-capture package test suites and JavaScript utilities. The tracked CI LTS pin is `.github/node-version`.
- Python runs the cataloger, skill-authoring utilities, MCP examples, and technology inventory script. The tracked CI pin is `.github/python-version`; `.replit` requests Python 3.11.
- `process-capture/*/package.json` files are private, standalone ESM packages at version `0.1.0` with no npm dependencies and the test script `node --test tests/*.test.mjs`.
- `artifacts/forge/package.json` is the private Vite/React frontend package for Skillz Forge; its build is deployed to GitHub Pages by `.github/workflows/deploy-pages.yml`.
- `mermaid/okhp3-mermaid-publish/package.json` is a private ESM package with Mermaid CLI `11.16.0` as a dev dependency. The root package is a workspace coordinator; application runtime packages live under `artifacts/`.
- Python requirements are local to `community/skill-creator` and `community/mcp-builder`. Do not assume a root virtual environment or dependency installation.
- `.github/workflows/refresh-technology-inventory.yml` is scheduled automation for version inventory updates. It is not the repository's general CI test suite.

## Validated commands

Run from the repository root.

```bash
# Check the full distribution catalog without writing generated files
python3 .agents/skills/okhp3-skill-cataloger/scripts/gen-skills-readme.py --full --check

# Validate one skill with the bundled strict validator
node .agents/skills/okhp3-skill-foundry/scripts/validate-skill-suite.cjs --root path/to/skill

# Run one process-capture package's tests
(cd process-capture/okhp3-process-intake-and-scope && node --test tests/*.test.mjs)

# Run the Mermaid theme-builder tests
(cd mermaid/okhp3-mermaid-theme-builder && node --test tests/*.test.mjs)
```

The full-index check discovers the root distribution skills in 17 active families. The project cataloger indexes the project-local support skills separately. Structural validators establish package integrity only, not task-quality uplift or production readiness; preserve their warnings and known test gaps in validation reports rather than treating them as release evidence.

For generated catalog work, use `okhp3-skill-cataloger` in catalog mode for `.agents/skills/README.md` and full-index mode for root `README.md` plus family inventories. Do not hand-edit generated sections. Do not run the technology refresh script casually because it makes network requests and writes the generated technology section and runtime pins.

## Change safety and conventions

- Preserve existing user changes and use minimal diffs.
- Keep `SKILL.md` and `README.md` uppercase. Skill names use lowercase kebab case and normally match their directory name, including the `okhp3-` prefix for OKHP3 skills.
- Keep every skill package directory at 36 characters or fewer; the portable Agent Skills name maximum is 64. Keep each path element at 64 characters or fewer and each repository-relative skill path at 180 or fewer.
- Keep domain skills composable. Mermaid domain skills defer audience, naming, registry, and validation to `okhp3-mermaid-core`.
- `okhp3-mermaid-update` changes content while preserving style. `okhp3-mermaid-repair` fixes syntax with minimum intervention. Do not merge these workflows.
- `okhp3-linkedin-voice` filters existing LinkedIn-bound text. It does not generate a post.
- Keep public-surface decisions routed through OverKill Hill. Glee-fully and AskJamie are contextual side doors, not alternate canonical homes.
- Keep employer references excluded by default. Every public-posting draft requires a public-context check; the LinkedIn post skill retains its explicit final scrub gate.
- Do not add em dashes to generated content. Preserve punchy standalone lines. AutoCAD version references, when relevant, use locked R10 wording.
- A rendered diagram is disposable output unless explicitly requested for retention. Never delete source or rendered output as part of repair.

## Support documents

Read only when relevant:

- `docs/STACK-POSITION.md`: stack architecture and ReFolDec relationship
- `docs/PUBLIC_SURFACES.md`: public information architecture and brand routing
- `docs/PUBLISHING.md`: maturity, release, registry, and promotion gates
- `docs/SECURITY.md`: skill supply-chain and data-safety rules
- `docs/CHANGELOG.md`: historical changes and release notes
- `docs/BACKLOG.md`: maturity model and promotion priorities
- `docs/TECHNOLOGY-INVENTORY.md`: runtime, dependency, and version posture

## Known gaps and maintenance notes

- Generated catalogs reflect the current filesystem: `README.md` reports 258 distribution skills in 17 active families, and `.agents/skills/README.md` reports 46 project-local support skills. The family `FAMILY.md` files are the inventory authority for their respective distribution directories.
- `skillz.manifest.json` is a machine-readable package summary and must stay synchronized with the current family and skill inventory when public metadata is refreshed.
- `docs/BACKLOG.md`, `docs/PUBLISHING.md`, and `docs/CHANGELOG.md` contain historical references to the old one-skill process-capture family and the removed `SKILLS.md` catalog. Do not treat those historical claims as the current inventory.
- The cataloger warns only for imported packages that intentionally do not declare a version; those warnings do not block structural catalog validation.
- There is no release tag and no repository-wide CI test command. Promotion remains gated by `docs/PUBLISHING.md`.

When a skill, family, maturity level, or generated catalog changes, re-run the structural and catalog checks, update this index, and record release-relevant changes in `docs/CHANGELOG.md`. Keep this file factual. Label inferences and unresolved owner decisions rather than filling gaps with assumptions.

Updated: 2026-08-27