AGENTS.md · git:20261013.89ccbeb · 2026-10-13 · sha256 b28851fbb335ab61
AGENTS.md git:20261013.89ccbebA
Immutable. This exact content never changes and is served at /api/v1/blob/b28851fbb335ab61.
# 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.
- Most product-specific guides are Russian.
- 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.