git:20261013.89ccbeb to git:20261013.df0a08f

# PROJECT KNOWLEDGE BASE

**Generated:** 2026-03-17 (working tree snapshot)

**Base commit:** 0bc69a8

**Branch:** main

## OVERVIEW

Collection of reusable skills for `Claude Code`, `Codex`, and similar AI-agent CLIs. The repo is documentation-first: each skill is a markdown knowledge package with optional `references/`, `scripts/`, and `evals/`. Distribution is through `npx skills add nordz0r/skills`.

The repository is no longer Russian-only:

- `README.md` is the primary Russian landing page.

- `README.en.md` is the English companion for discovery and catalog indexing.

- `agency-*` skills are English.

- Most product/domain guides are Russian.

## ROOT STRUCTURE

```text

skills/

├── README.md # Primary RU landing page + install/use index

├── README.en.md # EN companion README for discovery/catalogs

├── AGENTS.md # Repo knowledge base for coding agents

├── .gitattributes # Shell scripts forced to LF

├── .gitignore # IDE-only ignores

├── .claude-plugin/ # Claude Code marketplace + root plugin manifests

├── .agents/plugins/ # Codex/ChatGPT plugin marketplace catalog (generated)

├── plugins/ # Generated Codex plugin bundles (never hand-edit)

├── scripts/ # validate-skills.js + sync-codex-plugins.js

├── agency-*/ # 10 English meta-skills, each with evals/evals.json

├── tools/a_evolve_router/ # A-Evolve routing benchmark over skill evals

├── litellm-guide/ # LiteLLM SDK/proxy/provider/repo guide

├── elk-kibana-dashboards/ # Elasticsearch/Kibana dashboards and log analysis

├── preview-interview/ # Interview preparation workflow

├── nextcloud-admin/ # Nextcloud OCS API + WebDAV

├── nextcloud-collectives/ # Nextcloud Collectives wiki (OCS API + WebDAV)

├── open-terminal-guide/ # Open Terminal guide

├── open-webui-guide/ # Largest reference set

├── administering-linux/ # systemd / journald / host troubleshooting

├── docker-ops/ # Dockerfile + Compose v2

├── gitlab-ci/ # GitLab CI/CD + runners

├── ansible-playbook/ # Ansible playbooks / vault / lint

├── amnezia-vpn/ # AmneziaVPN / AWG on Linux + Docker

├── linux-routing/ # iproute2 PBR + nftables

├── amneziawg-openwrt-guide/ # AmneziaWG on OpenWrt

├── podkop-openwrt-guide/ # Podkop / sing-box on OpenWrt

└── zapret-openwrt-guide/ # zapret-openwrt guide

```

## CURRENT SKILL INVENTORY

### Agency family

- `agency-devops-automator`

- `agency-sre`

- `agency-incident-response-commander`

- `agency-security-engineer`

- `agency-database-optimizer`

- `agency-technical-writer`

All 6 remaining `agency-*` skills follow the same pattern:

- `SKILL.md`

- `evals/evals.json`

- no `references/`

- no `scripts/`

Design agency skills (`agency-ui-designer`, `agency-ux-architect`, `agency-ux-researcher`, `agency-whimsy-injector`) were removed 2026-09-20.

### Domain and workflow skills

- `administering-linux`

- `docker-ops`

- `gitlab-ci`

- `ansible-playbook`

- `amnezia-vpn`

- `linux-routing`

- `nextcloud-admin`

- `nextcloud-collectives`

- `litellm-guide`

- `open-terminal-guide`

- `open-webui-guide`

- `elk-kibana-dashboards`

- `preview-interview`

- `amneziawg-openwrt-guide`

- `podkop-openwrt-guide`

- `zapret-openwrt-guide`

- `atlassian`

## WHERE TO LOOK

| Task | Location | Notes |

|------|----------|-------|

| Root repo positioning / install / discovery | `README.md`, `README.en.md` | Keep both updated when adding or renaming skills |

| Trigger wording for a skill | `<skill>/SKILL.md` frontmatter | `description` is the main auto-trigger surface for agents |

| Frontmatter example | Any `SKILL.md` | `name` must match directory name; `metadata` is optional |

| Eval prompt examples | `<skill>/evals/evals.json`, `agency-*/evals/evals.json` | Useful for trigger QA and smoke tests |

| OpenClaw metadata example | `litellm-guide/` | Remaining `metadata.openclaw` / agent metadata examples |

| Script patterns | `atlassian/scripts/` | Python REST helpers; previously Lightpanda Node executors |

| Largest reference set | `open-webui-guide/references/` | 11 files; best example of deep multi-file documentation |

| Routing benchmark | `tools/a_evolve_router/` | Baseline/evolution loop for skill trigger wording |

| OpenWrt skill patterns | `amneziawg-openwrt-guide/`, `podkop-openwrt-guide/`, `zapret-openwrt-guide/` | Good templates for Russian infra/network docs |

| Linux host / CI skills | `administering-linux/`, `docker-ops/`, `gitlab-ci/`, `ansible-playbook/`, `amnezia-vpn/`, `linux-routing/` | Operator-focused RU guides; AWG on Linux is `amnezia-vpn`, OpenWrt AWG stays in `amneziawg-openwrt-guide` |

## CONVENTIONS

### Skill layout

```text

<skill-name>/

├── SKILL.md

├── evals/ # optional; used heavily by agency-* skills

├── scripts/ # optional; currently present in atlassian

└── references/ # optional; one topic per file

```

### Frontmatter

Follow the Agent Skills spec (https://agentskills.io/specification): top-level keys only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`; `name` ≤64 chars `[a-z0-9-]`, matches the folder, no `anthropic`/`claude`; `description` ≤1024 chars, no XML tags; `metadata` is string→string (the `metadata.hermes` map is the only tolerated nested block); body <500 lines; one `SKILL.md` per skill, translations under `references/`. `scripts/validate-skills.js` enforces all of this.

```yaml

---

name: skill-name

description: "Natural-language trigger surface for agent matching"

metadata: {...} # optional

---

```

### Naming and content

- Skill directories use `kebab-case`.

- `name` in `SKILL.md` matches the directory name.

- `description` should be concrete and rich in domain terms; avoid vague slogans.

- Reference files use lowercase topic names such as `api.md`, `config.md`, `troubleshooting.md`.

- Shell scripts follow `<skill>-<action>.sh` when they are skill-specific.

- Code snippets and variable names stay in English even inside Russian docs.

### Language model

- Root docs are bilingual: Russian primary, English companion.

- `agency-*` content is English.

- Do not assume "all docs are Russian" anymore.

### Git and repo hygiene

- Conventional commit style fits the repo well: `feat(scope):`, `fix(scope):`, `docs(scope):`.

- `.gitattributes` enforces LF for `*.sh`.

- `.gitignore` only ignores `.idea` and `.vscode`.

- No `package.json`, no GitHub Actions, no `LICENSE` file, and no `.claude/settings.local.json` are currently present in the repo root.

## NOTABLE PATTERNS

- Documentation-first repo: the skills are the product.

- Repo-level discovery matters: `README.md` and `README.en.md` are part of search/catalog visibility, not just human docs.

- Runtime auto-triggering still depends primarily on each skill's `SKILL.md`, especially `description`.

- `tools/a_evolve_router` tests routing quality from `<skill>/evals/evals.json` against isolated workspace copies; it is safe to delete `.workdir/`.

- Env-based configuration is common for integration skills: `NEXTCLOUD_URL` and similar variables are documented in-skill.

- `open-webui-guide` has the deepest reference tree and is the best template for a large guide.

### Codex plugin layout (generated)

- `.claude-plugin/marketplace.json` is the single source of truth for bundle grouping.

- `node scripts/sync-codex-plugins.js` derives `.agents/plugins/marketplace.json` and `plugins/<bundle>/.codex-plugin/plugin.json` + `plugins/<bundle>/skills/<skill-name>/` copies from it.

- `plugins/` is fully derived: sync wipes and rebuilds it. Never hand-edit anything under `plugins/`.

- Sync copies these skill subdirs: `references`, `scripts`, `agents`, `evals`, `assets`, `lib`, `examples`.

- README assets (banner SVGs, GIFs) live in `.github/assets/`; `.github/social-preview.png` is the 1280×640 social card (upload it in repo Settings).

- Adding a skill or re-bundling means: edit `.claude-plugin/marketplace.json`, re-run the sync script, commit both source and generated artifacts.

- `scripts/validate-skills.js` runs the sync in `--check` mode and fails if the generated layout drifted.

## COMMANDS

```bash

# Claude Code Plugin Marketplace:

claude plugin marketplace add nordz0r/skills

claude plugin install all-skills@nord-skills

claude plugin install agency-skills@nord-skills

claude plugin install infra-linux@nord-skills

claude plugin install ai-tools@nord-skills

claude plugin install openwrt-routing@nord-skills

# OpenAI Codex Plugins (reads .agents/plugins/marketplace.json + plugins/):

codex plugin marketplace add nordz0r/skills

codex plugin add openwrt-routing@nord-skills

codex plugin list

# Validation script (includes a Codex layout sync check):

node scripts/validate-skills.js

# Regenerate Codex plugin layout after changing skills or bundles:

node scripts/sync-codex-plugins.js

node scripts/sync-codex-plugins.js --check # CI mode: exit 1 if out of sync

# npx skills (Codex / OpenClaw / Agent CLIs):

npx skills add nordz0r/skills -l

npx skills add nordz0r/skills

npx skills add nordz0r/skills -g

npx skills add nordz0r/skills -s litellm-guide -g

```

## NOTES

- Current inventory: 26 skills total.

- `pr-lens-diagrams` is a standalone skill (`SKILL.md` in English, Russian text in `references/README.ru.md`) with `scripts/` (setup/build/record) and `examples/`; grouping `Diagrams` in `skills.sh.json`.

- `agency-*` accounts for 6 remaining engineering skills (design four removed 2026-09-20).

- `open-webui-guide` has 11 reference files and is still the largest single documentation set.

- `litellm-guide` has 6 reference files, an OpenAI agent metadata file, and evals for `a_evolve_router`.

- `telegram-formatting` is a standalone skill (not in `ai-tools`); grouping `Telegram` in `skills.sh.json`.

- Removed design agency skills (2026-09-20): `agency-ui-designer`, `agency-ux-architect`, `agency-ux-researcher`, `agency-whimsy-injector`.

- Removed `lightpanda-browser` (2026-09-20): unused in this estate; Playwright skill already gone.

- Removed `omniroute-guide` (2026-10-03): OmniRoute is retired in this estate and will not return.

- Removed `basic-memory-workflow` (2026-09-20): project memory moved to OpenViking (`ov`) and graft.

- Removed in September 2026 after a skills.sh security-audit review (unremediated MEDIUM warnings): `playwright-skill` (arbitrary JS executor + auto npm installs), `ollama-search`, `qdrant-codebase-search` (`npx -y` runtime code fetch). Stale entries persist on skills.sh with their install counts.

- Hermes Agent compatibility: skills sit at the repo root, so `hermes skills install nordz0r/skills/<name>` works directly (verified live on v0.21.0, including skills absent from skills.sh); as a tap the repo needs `"path": ""` in `$HERMES_HOME/skills/.hub/taps.json` (the `tap add` CLI defaults to `skills/`). Hermes walks its large default taps before user taps, so tap skills may not surface in `search`/`browse` right away. Install/update commands are documented in both READMEs (section 4).

- skills.sh listing is install-telemetry-driven (no GitHub crawler): a skill appears on the repo page after its first `npx skills add` install and never disappears on rename — stale entries (e.g. the old `pbr-openwrt-guide` name) persist with their install counts.

- `scripts/validate-skills.js` rejects `: ` inside plain (unquoted) frontmatter scalars: strict YAML 1.2 parsers — including the one in `npx skills` — treat it as a nested mapping and skip the skill (this is how `agency-ui-designer` silently dropped out of installs in 2026).

- The old AGENTS snapshot was stale: it described only 5 skills and predated the bilingual root README.