DEV Community: Evgeniy Uryadov

I Turned My Agency's Rituals into Agent Skills. Here's How They Work

Evgeniy Uryadov — Wed, 14 Oct 2026 07:18:07 +0000

Yesterday evening I installed ten new skills into my coding agent. They were written by Emil Kowalski, the developer behind the Sonner toast library, and they teach it design engineering: when not to animate at all, which easing curves to use, how to stress-test a UI with worst-case data. The whole install took about five minutes, most of it spent reading the security scan.
Today the agent writes animations and mobile layouts noticeably better. Nobody rewrote the model. The difference is a folder with a markdown file.

What a skill actually is

A skill is a directory with a SKILL.md file and optional supporting files: templates, checklists, small scripts. The file is plain markdown. Here's a minimal real example:

---
name: seo-audit
description: "Audit a client site before delivery. Use when asked to"
  "check the site", "run an audit", or before handing a project over.
---
## Workflow
1. Crawl the site, collect titles/descriptions/headings
2. Check structured data and canonical tags
3. Report as a table: severity, page, fix
## Hard rules
- Report only. Do not fix anything until asked.

The frontmatter carries the matching surface: name becomes the /seo-audit command in chat, and description is what the agent reads to decide whether this skill fits the current task. The body is the procedure.
The clever part? loading. At session start my agent holds only names and one-line descriptions for all 53 skills I keep, which costs a couple of kilobytes of context. The full text of a skill loads only when the task matches or I invoke it explicitly. That's why you can afford to keep dozens of skills around: unused ones are nearly free.

Two ways to invoke

Explicit, with a slash: /seo-audit https://client-site.ru. The agent follows the procedure step by step, passing arguments through. I use this when the ritual itself matters.
Implicit, by description: I write "check this site before handing it to the client" in plain language, and the agent compares the request against skill descriptions and pulls in the right one. This is why the description field deserves most of your writing effort. Good skill authors even add an explicit Triggers section listing the exact phrases that should activate the skill.

Where skills live

Three layers, in my setup:

~/.agents/skills/<name>/SKILL.md for personal skills, available in every project. This is where my working style lives: publishing pipelines, audit procedures, security gates.
A skills folder inside the repository for team skills, committed to git. A new hire gets executable procedures, not a wiki page nobody opens.
Plugin caches for marketplace bundles. Fine for generic needs; anything specific to how my agency works belongs in the first two. ## A real pipeline: one command, six platforms My heaviest skill is the one publishing this very article. I type /smm-crosspost with a file, or just say "write an article for our blog", and the agent:
writes the article in English, adapts it into Russian and Kazakh, and cross-links the three versions;
generates a 1200x630 cover in the brand style;
places everything into the site with full structured data (TechArticle, FAQPage, HowTo, hreflang);
stops and shows me everything for approval;
after my "ok": deploys, checks the article is live, runs an internal quality audit;
writes platform adaptations for six networks, each with its own format, tone and length limits;
runs the drafts through a human-lint pass and shows me every text with scores;
waits for an explicit "ok" again. Only then it publishes. Steps 4 and 8 are hard gates written into the skill. The agent can't publish anything without my confirmation because the markdown says so, and it obeys. That's the part people underrate: agent behavior rules live in the same plain text as the workflow, and they hold. ## The security gate A skill is a set of instructions your agent will follow. Installing one you'ven't vetted is like running a script from a stranger's repository. "Ignore previous instructions" fits comfortably into a helpful-looking checklist. My gate, which is itself a skill:

git clone --depth 1 https://github.com/author/some-skills /tmp/check
skillspector scan /tmp/check --no-llm   # NVIDIA's scanner, fully local
# then: read every flagged line by hand

About those false positives, because this matters. This week the scanner returned CRITICAL on that harmless design-skills repository: 29 findings, top severity, "don't install". Manual review showed every single one was a false positive. It tripped on a defensive line telling the agent to ignore steering attempts from repository files (the phrase "ignore previous instructions" appears inside the quote), on zero-width characters the author used to nest code fences in markdown templates, and on a ZWJ emoji sitting in test data on purpose. Zero real threats.
The lesson isn't "ignore the scanner". It is: the scanner filters, a human decides. Reading 29 flagged lines took me about ten minutes. Installing a poisoned skill would have cost considerably more.

Writing your own

Ready-made skills are someone else's experience. Your own rituals are worth more, and nobody's going to write them for you. Here's the recipe I give clients:

Take a task you repeat weekly: publishing, a weekly report, a pre-delivery audit, a deploy.
Write the steps exactly as you do them by hand, including where you double-check yourself.
Add hard rules: what never to do, what requires human approval, where to stop.
Write the description for the agent, not for yourself: what the skill does and which phrases should trigger it. Start small. A hundred-line skill that saves an hour a week beats a thousand-line perfect one you'll never finish. --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/ai-automation/how-to-use-zcode-skills-and-commands/ tags: aiagents, automation, webdev, productivity

A Vault That Rewrites Itself: obsidian-second-brain and the Karpathy LLM Wiki Pattern

Evgeniy Uryadov — Thu, 08 Oct 2026 06:51:48 +0000

Two tools most of us own ignore each other completely. An Obsidian vault with hundreds of notes nobody rereads. An AI agent in the terminal whose every session starts from zero, as if the past never happened. The obsidian-second-brain repository glues them together: 4.7k stars, MIT, authored by Eugeniu Ghelbur. The README's own formula: an evolution of Karpathy's LLM Wiki pattern, a vault that rewrites itself.
Here's a review, plus why I read the whole thing with deja vu: my business CRM runs on the same pattern.

The pattern first

Karpathy's LLM Wiki idea: a knowledge base in wiki form, maintained by an LLM. The model adds pages and links them, flags contradictions for manual resolution, surfaces patterns on request. The human owns the knowledge, the model maintains it.
The weak spot: it's passive. The wiki grows when you ask, and contradictions sit until you resolve them. This repo pushes the pattern into active form.

Four layers, 47 commands

The repo gives a CLI agent (Claude Code, Codex, Gemini CLI and four more) a command set that operates directly on your vault.

Operations (30). Ingest URLs, PDFs, audio, screenshots into normalized notes. /obsidian-reconcile resolves contradictions. /obsidian-health lints the vault. /obsidian-architect documents a codebase into notes.
Thinking tools (9). The part I care about most. /obsidian-challenge makes the vault argue with you from your own history. /obsidian-emerge hunts unnamed patterns. /obsidian-connect bridges knowledge domains.
Context (1). /obsidian-world loads identity and state with token budgets, from a light L0 to a full L3.
Research (7). Vault-first: /research-deep scans your notes first and researches only the gaps outside. Plus four scheduled agents: morning, night, a Friday review, a Sunday health check. The vault lives without you. That's the design goal. ## The part that's actually engineering Two rules separate this from "plug GPT into notes". Open Knowledge Metabolism. Every fact must be timeless, dated, or a pointer. Slow-changing knowledge lives in the note; fast-changing facts link to a live source with an "as of" date. There's a spec and a linter. Bi-temporal facts. The vault remembers when a fact was true and when it learned about it. It sounds academic until someone asks "when did this stop being true", and someone always asks. Add the inversion I like most: an AI-first note format, notes written for an agent to read, with frontmatter, recency markers and verbatim sources. For decades we adapted machines to documents. Here documents adapt to the machine. And the restraint: bounded recall through a hook, at most four notes of roughly 900 characters per prompt, so memory doesn't eat the context window. 763 tests in CI, eight builds per platform. It's built like infrastructure, not like a prompt collection. ## The principle to steal "Your vault outlives any CLI." Agents change every six months. Knowledge in markdown belongs to none of them. Switch the tool, keep the files. A rare case where the right architecture is also the cheapest one. ## The deja vu: our CRM runs on this pattern I've been building business automation for 14 years, and my company's CRM is a production implementation of the same idea, on business entities instead of notes. What exists today, not on a roadmap:
The vault is the source of truth. Clients, deals, tasks, invoices, infrastructure and correspondence: markdown with frontmatter in an Obsidian vault. A task tagged urgent and important lands in the right quadrant of an Eisenhower matrix on the dashboard, automatically, like this:

---
title: "Connect payment webhook to the CRM"
urgent: true
important: true
hours: 3
---

Agents read and write directly. A board of director roles works on the same files: a CEO holds the weekly plan, a CFO holds cash and price floors, a commercial director holds receivables. Decisions land in a shared journal, a human approves what matters.
Panels read, the vault stays. A promotion dashboard compiles semantics, content coverage, five social networks and traffic into one JSON file that both the agent and the owner read. The vault never becomes a database you can't open.
Data discipline. Sensitive client fields are encrypted in a vault that locks itself, and the company is a registered personal-data operator. ## How a business version differs The cost of an error. In a personal knowledge base a wrong note costs a reread. In business, an agent that records a payment wrong or leaks personal data costs money and reputation. So triple down on what the personal version treats as optional: human approval of critical actions, encrypted personal data, and a decision log that shows who did what and why. In about two years the pattern has traveled from a tweet to systems with hundreds of tests, and to CRMs companies actually run on, If you've got an Obsidian vault full of knowledge, this repo is the shortest path to giving your agents persistent memory. If you're running a business, the same pattern works there too, just bring the discipline along. --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/ai-automation/obsidian-second-brain-obzor/ tags: aiagents, obsidian, knowledgebase, productivity

I Gave My Markdown CRM a Second Brain: obsidian-second-brain in Practice

Evgeniy Uryadov — Tue, 06 Oct 2026 10:53:19 +0000

My CRM isn't an app. It's a folder of Markdown files in an Obsidian vault, and a set of CLI agents that read and write those files. Client chats land there, invoices are generated from it, monitoring alerts get routed through it. The engine is open source (MIT): crm.automata.sale.
It worked for a year. Then it didn't, twice, in ways that cost real money. This post is about the fix: I adopted the open-source obsidian-second-brain methodology in one day, and I'm including the command cheat sheet I now use daily.

Two failures that forced the methodology

Failure one: an agent ran a cleanup pass over the ticket folder and deleted live tickets. Money was attached to them. The rules that should have prevented it existed, but they lived in the agent's session memory. Which is to say: they didn't exist.
Failure two: structural decisions (kill a project, move a client to on-demand monitoring, pick an e-document stack) lived in chat history. Six months later neither I nor the agent could answer "why did we choose X".
Both failures share one root: the database had no discipline. obsidian-second-brain is that discipline, packaged as commands for CLI agents.

The Folder Map trick: no restructuring required

Migration risk was my main concern. The pipeline runs 30+ live automations on a 15-minute communication cycle. Moving to the repo's default layout (wiki folders, daily notes, kanban boards) would break everything.
The methodology handles this natively: commands resolve folders not by hard-coded paths but through a Folder Map table in the vault-root instruction file, and when that map exists, it wins over the built-in defaults. Mine maps note types onto the folders I already had:

| Note type          | Folder                  |
|--------------------|-------------------------|
| Client (company)   | 10_Clients/             |
| Lead / prospect    | 15_Leads/               |
| Task               | 30_Tasks/               |
| Invoice            | 30_Invoices/            |
| Decision (ADR)     | 30_Decisions/           |
| Project            | 50_Projects_Wiki/       |
| Raw sources        | 60_Documents/, Clippings/ (immutable) |

Daily notes stayed out: the message feed replaces them. Kanban stayed out: the dashboard task matrix replaces it. I took the rules and the tools. The structure stayed mine.

The four commands (the cheat sheet)

Each command is a thin skill wrapping the repo's command spec, triggered by a spoken phrase:
| You say | Command | What the agent does |
|---|---|---|
| "save to vault" | osb-save | Scans the session, files updates into client cards as body blocks, tasks through the CRM pipeline, facts with date stamps, plus an ops-log entry |
| "log this decision" | osb-decide | A dated line in the project card, or a full ADR (context, options, rationale, consequences) with the --formal flag |
| "check the vault" | osb-health | Runs a health scan, reports broken links, missing frontmatter, duplicates, stale stamps; edits wait for approval |
| "where's the truth on X" | osb-reconcile | Sweeps contradictions across cards, tickets, and agent memory; clear winners update with history preserved, ties become conflict cards |
The audit scanner is plain Python, no external keys:

python3 obsidian-second-brain/scripts/vault_health.py --path ~/crm-vault --json

Noisy folders get excluded via a .vault-config.json next to the vault.

What the first audit found

1,254 notes scanned, 596 after excluding chat dumps and archives:

158 wikilinks pointing to pages that don't exist
76 notes without frontmatter
4 title duplicates, 8 empty folders None of this was surprising. What changed is that it now surfaces in a report instead of rotting silently. ## What I deliberately skipped The repo ships a research toolkit (Perplexity, Grok, YouTube transcripts) that needs external API keys. I run this pipeline on my own infrastructure without external LLM services, so those stayed out. The core set (writing rules, ADRs, audits, reconciliation) depends on no keys. ## Takeaway If your agent's operating rules live in "somewhere", they don't live anywhere. A Folder Map, a decision log, and four phrases are cheap insurance, and none of it required touching the 30+ automations already in production. tags: aiagents, automation, markdown, productivity --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/ai-automation/automata-crm-second-brain/

I Built an AI Tutor That Cannot Do the Homework

Evgeniy Uryadov — Mon, 05 Oct 2026 13:43:32 +0000

My son is nine, in second grade, and has ADHD. He can calculate, but store-bought trainer apps reward taps, not understanding, and he finishes each one in an evening by guessing. So I built our own tutor around his actual school textbook (the skin is a space school: missions follow the Apollo 11 route, 15 rockets in the collection), and the whole architecture serves a single ban: the LLM is not allowed to solve the task.
This post is my engineering story: the constraint that shapes everything, the content pipeline, the pedagogy encoded in data, and the surprising part, the paper notebook.

The ban that shapes the architecture

Most AI homework helpers on the market do the homework. Mine can't, and not because of a polite system prompt. The design is structural, not polite:

The mentor endpoint receives only the task text. The correct answers live in a table the LLM layer never reads, so there's nothing to leak and nowhere to jailbreak.
The prompt must end every reply with one question that moves the child forward. No final answers, no "the answer is".
The similar-example mode works through an analogous problem with different numbers. It may name that example's answer, never the original task's. If you take one thing from my story: isolate the answer from the model, then design the prompt around a question-ending rule. Bans you can verify in code beat bans you can only write in prose. I trust the first kind. ## Content pipeline: the textbook is the source of truth Homework comes from a specific textbook, so the dataset has to match it verbatim: our numbering, our wording, so the notebook can be shown to the teacher in the morning. I forbid generative paraphrase, and the pipeline enforces it: page scan (PNG, 300 dpi) -> vision model with a narrow prompt: "transcribe task N verbatim" -> second pass on disputed fragments -> verification against the scan; the scan always wins -> a card in the dataset Full-page transcription by vision models is unstable. Narrow one-task prompts are reliable, so my pipeline reads pages piece by piece. Why am I so paranoid? Here's a real catch from the first weeks: an external agent prepared five tasks for a page, and verification against the scan flagged one. In an angle-counting task the agent had picked the wrong figure and "found" a right angle in a hexagon, while on the scan the right angle belongs to the pentagon. Without that check my son would've memorized a wrong fact and carried it to class. Six weeks in: 22 pages across two textbooks, 117 exercises, zero wording invented by feel. ## Pedagogy encoded in data, not in pixels The method I lean on comes from the open learn method (the amosblomqvist/learn repo): understanding is a connected dependency graph, not a pile of facts. Unconditional truths first, derived steps second, every node motivated before it's established, then linked to the previous one and fixed with a quiz. In my app it lives in the task schema, roughly:

{
  "text": "Verbatim from the scan",
  "hook": "Why this skill matters, one sentence",
  "prev": "Link to the node the child already owns",
  "probes": ["Easy check of the supporting skill"],
  "quiz": {
    "correct": "7 - 4 = 3",
    "wrong": ["Mutations of the correct line, same shape, real diagnostic mistakes"]
  }
}

Three fields do the teaching. In practice, the hook motivates ("inverse problems are a time machine: reconstruct the question from the answer"). The probe questions come before the hard task: before the cucumber word problem, "what is 6 + 4?" My kid with ADHD gets an early win and enters the real task without fear. Distractors are mutations of the correct answer, same length, same shape, each a mistake a child actually makes. When my son picks wrong, he gets an explanation, not a red cross.

The notebook bridge

The big discovery of my son's first grade: for half the class the problem isn't arithmetic, it's formatting. The teacher grades the notebook, not the app. So after each solved task the app renders a model entry on a squared sheet: a four-cell margin with a red line, the date on the 11th cell, columns three cells apart, wrapping to sheet width, a handwriting font in blue ink.
My son solves in the app, where input is easy and feedback is instant, then transfers to paper following the model. Homework is still delivered the way school wants it, and that's non-negotiable.

Deliberately boring tech

React 18, TypeScript, Vite, Tailwind. Express with better-sqlite3, cookie sessions, pm2 and nginx. An LLM behind the mentor buttons (Explain, Hint, Similar example; GLM via the z.ai API), replies spoken aloud with speech synthesis. Content is prepared by an agent in the IDE following the pipeline above; a human approves publication. It's the same principle as my grown-up automations: the agent prepares, the human decides.

Why systems like this are rare

I count five conditions that must hold at once, and the combination is scarce:

A teaching method pushed down to data fields, not gamification painted over a PDF.
An agent content pipeline with scan verification, because without it an LLM hallucinates a textbook within a week.
LLM discipline: the mentor is designed around a ban, with answers isolated from the model.
Respect for the school standard: the paper notebook still has to look right.
An engineer-parent, that's me, watching every evening where the system fails. The edtech market is huge, but it's mostly content platforms without an AI loop, in my view, or AI solvers that do the homework for the child. The middle, a machine that teaches how to learn from your own textbook, is nearly empty. ## What's next A live mentor key, new pages as the school program moves on, and the main experiment: the same content model for a whole class, with teachers watching progress through public links. If you're building something like this for your kids, I'd love to trade notes. --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/ai-automation/space-academy-ai-tutor-from-a-textbook/ tags: aiagents, edtech, llm, react

What Building Redis, Git and an LLM From Scratch Taught Us About Using Them

Evgeniy Uryadov — Mon, 05 Oct 2026 13:43:30 +0000

There is a GitHub repository with about 550,000 stars called build-your-own-x. It is not a library. It is a curated catalog of step-by-step tutorials where people rebuild the technologies we all use daily: a SQLite clone in C, Redis in C++ or Python, a container in a hundred lines of Go, git from the inside, a vector search engine, even a small GPT. CC0 licensed, started by Daniel Stefanovic, maintained by CodeCrafters.
The epigraph is Feynman: "What I cannot create, I do not understand." This post is about what happens to a team that takes that seriously.

The mechanic that changes how you work

Take Redis. You use it for cache and queues. Then you spend an evening on a mini-Redis tutorial and the wire protocol stops being abstract:

*2
$3
GET
$3
key

That is a GET command on the RESP protocol. Once you have parsed one with your own code, connection pool behavior, timeouts and persistence settings turn from copied flags into decisions. Same shift happens with B+trees after you build a storage engine page by page: EXPLAIN output starts reading like a sentence.

How we actually use the catalog

We do not read it cover to cover. We pull a tutorial when a task needs a fast prototype or a mental model:

RAG and agents. LLMs from scratch and Karpathy's Zero to Hero cover tokens, embeddings, attention. Chunking and retrieval choices stop being folklore.
Search and semantics. The vector space indexing engine and TF-IDF tutorials are the shortest path from TF-IDF to BM25 to embeddings, which is exactly the line search engines followed and the line LLMs read your site along today.
Slow e-commerce queries. Let's Build a Simple Database teaches indexes and transactions from the inside.
Front end. Build your own React explains where render time actually goes, which matters in headless setups. ## The part that is not about code Three effects we can put a business value on:
Juniors level up cheaper. Assign a "build X" section matching your stack, and framework knowledge turns into platform understanding. You notice it in code review.
Contractor vetting. Ask a candidate to explain what happens between a button press and data landing in the CRM. People who built a web server or a database answer in terms of HTTP, transactions and queues. People who only know a framework retell its marketing.
Build vs buy discipline. Half of SaaS overspending is fear of simple internals. A team that built a mini version once estimates soberly what to buy and what is a week of work that stays yours. ## Honest limitations Tutorial code is educational: no production error handling, security or load. We prototype with it and run proven systems in production. And each tutorial is hours, not an evening scroll. The return is compounding: everything you build once, you use correctly for the rest of your career. ## Where to start
E-commerce owner: Database and Redis sections, mini-Redis in Python
SEO or marketing: Search Engine section, TF-IDF first
AI project: Neural Network and AI Model sections, Zero to Hero lectures
Team lead: Docker and Git, containers in 500 lines We keep a full breakdown with a role table on our blog: Build Your Own X: why this tutorial repo is good for business. --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/development/build-your-own-x-guide/ tags: programming, ai, learning, webdev

I Replaced Three Marketing Reports With One Screen

Evgeniy Uryadov — Mon, 28 Sep 2026 17:37:52 +0000

For 14 years my promotion workflow looked like most small businesses: an SEO contractor sent a monthly ranking report, an SMM plan was written from inspiration, and traffic lived in an analytics account nobody opens daily. Three worlds, zero connections.
This month I shipped an update to my own CRM that closes the loop. Here's the engineering story.

The loop

Semantic gap -> task -> article -> five networks -> traffic -> correction.
Everything below exists to keep that loop visible on one screen.

1. A collector that speaks numbers

I wrote a collector script that pulls four data flows into a single JSON file:

Traffic. Visits by day, 30-day totals, month-over-month delta, organic share. It talks to a self-hosted analytics module through its REST API.
Semantics. My project's semantic core: 1,188 search phrases in 15 clusters.
Coverage. The core matched against the live sitemap. Blog slugs are Cyrillic transliterated to Latin, with an exceptions map for words that already live in Latin (bitrix, crm), so I can match cluster phrases to URLs. Coverage comes out at 80%, and the gaps come out as a ranked list. That list is a computed content plan, not a guess.
SMM. Publication counts and statuses read straight from the pipeline's Postgres, plus drafts waiting in the queue. The JSON feeds a REST endpoint, the endpoint feeds a CRM tab, and one Refresh button re-runs the collector. It's current again about a minute later. ## 2. A content pipeline with a taste test I write each article once; an agent adapts it per platform. Telegram, VK and MAX for the Russian audience, Dev.to and LinkedIn in English. Limits and tone differ, and the pipeline validates length before anything ships. The part I care most about is the linter. Before a human sees a draft, it runs five checks modeled on what public AI detectors measure: sentence-length variation, concreteness, stock vocabulary density, typographic fingerprint, and voice. Machine-written drafts fail, and they're rewritten until they pass. That gate is why this post doesn't read like a template. ## 3. A board that reads the numbers My CRM runs an AI board of directors: a CEO role tracking a weekly plan, a CFO watching cash and price floors, a commercial director on receivables. With this update they get marketing KPIs too: visits delta, semantic coverage, posts shipped in 30 days, the top uncovered cluster. When a verdict lands in the shared journal, it's backed by the same numbers the screen shows. ## What changes in practice If you run promotion for a small business, three things change:
"What should I write next" becomes a computed answer. The system names the uncovered cluster; I write.
"Did that post bring traffic" is one glance instead of three logins.
Marketing spend defends itself with the dashboard your money people already read. ## What's next Next stop is a Google Search Console adapter, so the loop closes on queries and clicks from search itself. The design leaves room for it: collectors are pluggable, and the screen doesn't care where a number came from. --- This article was prepared with AI assistance (drafting and adaptation) and reviewed by the author before publishing. Originally published at https://automata.sale/en/blog/ai-automation/automata-crm-pult-prodvizheniya/ tags: aiagents, automation, marketing, indiehackers

Shipping a MAX Messenger Bot and Channel in One Session — With an AI Agent Doing the Grunt Work

Evgeniy Uryadov — Sun, 27 Sep 2026 18:58:46 +0000

MAX is the messenger Russian business audiences are actively migrating to (2026). I needed a presence there: a bot, a public channel, and an auto-posting pipeline from my blog. The classical path is an evening with docs and a developer console. Instead, I gave the task to an AI coding agent (ZCode) in one sentence and supervised the execution.
This post is the engineering debrief: what the agent built, and the three undocumented traps we hit — the parts you won't find in the official docs.

What the agent shipped in one working session

A bot registered on the MAX partner platform (verified sole-proprietor profile required; moderation passed within hours).
A TypeScript publisher: API client, error classification (transient / auth / captcha / ToS / validation / UI-drift), a rate-limited scheduler, and per-platform text adaptation.
A public channel with the bot as admin.
The first automated post — this very text, in fact. ## Trap 1: The silently clipped token The API token copied manually from the platform UI was rejected with Invalid access_token. The reason was embarrassingly mundane: manual text selection clipped the end of the string. Copy with the icon, not with the mouse. Lesson for anything that stores tokens: validate length or do a round-trip health check (GET /me) before assuming the credential is wrong elsewhere. ## Trap 2: The base URL in the docs is dead The official documentation names platform-api2.max.ru as the API host. It did not respond — from Russia, and (we checked through a US relay) from abroad either. The working host turned out to be botapi.max.ru, discovered by controlled probing. Young-platform reality: docs drift. Build your client behind an interface so the base URL is a config value, not a constant. ## Trap 3: A fresh bot is invisible in channel admin search The documented flow — "add the bot as a channel member, then make it an admin" — assumes you can find the bot in the admin picker. You can't: until published to the catalog, a bot doesn't show up in channel settings search at all. The working sequence:
Open a direct dialog with the bot by its exact link and press Start.
In the channel: Subscribers → Add subscribers — now the bot appears among your recent contacts.
Add it, then promote it to admin with publish rights. Bonus undocumented behavior: the channel's chat_id is not discoverable statically. It arrives as a bot_added event in the bot's update queue — you subscribe (GET /updates) and read it from the event. ## How the pipeline works now One phrase to the agent ("publish this article") from any project triggers:
the article lands on the blog (Astro, three languages: ru/en/kk with hreflang);
the agent writes a separate adaptation per platform — different hooks, lengths, and tones, not copies;
every text waits for explicit human approval before anything goes out;
posts land on Telegram, VK, MAX, and now DEV — with the original article's URL set as canonical_url on platforms that support it. ## Cheat sheet
Host: botapi.max.ru (as of Sept 2026).
Auth: Authorization: <token> header — query parameters are deprecated and rejected.
Token: copy via the UI icon; verify with GET /me.
Channel: dialog with bot → Start → add via Subscribers → promote to admin.
chat_id: from the bot_added event in GET /updates.
Rate limits: comfortable for content posting (a handful of posts per day is nowhere near them). Originally published at https://automata.sale/en/blog/ai-automation/max-bot-i-kanal-cherez-zcode-agenta/ --- This article was prepared with AI assistance (drafting and adaptation by a coding agent) and reviewed by the author before publishing.