pachca · lookinway · Jul 8, 2026 · Jul 8, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -35,7 +35,7 @@ review generated diffs → commit. Branch from `origin/main`; open a PR
 | Generated | Source of truth |
 |-----------|-----------------|
 | `packages/spec/openapi.yaml` | `packages/spec/typespec.tsp` (then `npx turbo build --filter=@pachca/spec --force`) |
-| `apps/docs/public/llms*.txt`, `public/**/*.md`, `public/skill.md`, `public/.well-known/**`, `public/workflows.arazzo.yaml`, Postman collection | `apps/docs/scripts/generate-llms.ts` + `scripts/skills/` |
+| `apps/docs/public/llms*.txt`, `public/**/*.md`, `public/skill.md`, `public/.well-known/**`, `public/workflows.arazzo.yaml`, Postman collection, root `SKILL.md` + `skill.json` | `apps/docs/scripts/generate-llms.ts` + `scripts/skills/` |
 | `packages/cli/src/commands/**` (except `auth`/`config`), `packages/cli/CHANGELOG.md` | `packages/cli/scripts/generate-cli.ts`; `src/data/changelog.json` |
 | n8n node files | `n8n-nodes-pachca` generator |
 | `AGENTS.md` (this file) | `apps/docs/scripts/skills/generate.ts` (`generateAgentsMd()`) |

diff --git a/README.en.md b/README.en.md
@@ -0,0 +1,180 @@
+# Pachca API
+
+[![CI](https://github.com/pachca/openapi/actions/workflows/check.yml/badge.svg)](https://github.com/pachca/openapi/actions/workflows/check.yml)
+[![npm](https://img.shields.io/npm/v/@pachca/sdk)](https://www.npmjs.com/package/@pachca/sdk)
+[![npm](https://img.shields.io/npm/v/@pachca/cli)](https://www.npmjs.com/package/@pachca/cli)
+[![npm](https://img.shields.io/npm/v/@pachca/generator)](https://www.npmjs.com/package/@pachca/generator)
+[![npm](https://img.shields.io/npm/v/n8n-nodes-pachca)](https://www.npmjs.com/package/n8n-nodes-pachca)
+[![PyPI](https://img.shields.io/pypi/v/pachca-sdk)](https://pypi.org/project/pachca-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Русская версия: [README.md](README.md)
+
+Unified Developer Experience Platform for the [Pachca API](https://dev.pachca.com) — the REST API of Pachca, a corporate messenger. A single source (TypeSpec + workflows.ts + examples.ts) generates artifacts for every channel: web docs, CLI, SDKs, an n8n node, agent skills, and LLM context.
+
+**Docs**: https://dev.pachca.com · **OpenAPI**: https://dev.pachca.com/openapi.yaml · **Authorization**: https://dev.pachca.com/api/authorization · **Changelog**: https://dev.pachca.com/updates · **Postman/Bruno**: https://dev.pachca.com/pachca.postman_collection.json
+
+## CLI
+
+```bash
+# Zero-install (npx)
+npx @pachca/cli messages create --entity-id=123 --content="Hello!" --token $PACHCA_TOKEN
+
+# For regular use
+npm install -g @pachca/cli
+pachca auth login
+pachca messages create --entity-id=123 --content="Hello!"
+pachca guide "send a message"  # CLI guide
+
+# Built-in API reference right in the terminal (for agents)
+pachca api ls                          # list every endpoint
+pachca api POST /messages --describe   # params, body, example
+pachca api POST /messages -f message[content]="Hello"  # direct request
+```
+
+Every API method is available as a command: typed flags, validation, four output formats (table, JSON, YAML, CSV), cursor pagination, multiple auth profiles, and a non-interactive mode for CI and AI agents. The `pachca api` command sends direct requests to any method and ships a built-in API reference (`ls`, `--describe`, `--spec`, `--docs`) from the same OpenAPI spec — an agent never needs to open the docs website.
+
+**Docs**: https://dev.pachca.com/guides/cli
+
+## Agent Skills
+
+AI agents use CLI-first skills with step-by-step workflows, zero-friction authorization, and automatic permission checks.
+
+### Install (40+ agents)
+
+```bash
+npx skills add pachca/openapi
+```
+
+### Compatibility
+
+| Agent | Path |
+|-------|------|
+| Claude Code | `CLAUDE.md` → `AGENTS.md` |
+| Codex CLI | `AGENTS.md` |
+| OpenCode | `skills/` |
+| Cursor, Windsurf, Continue, 40+ more | Auto-detected |
+| Manual install | `cp -r skills/pachca-* <path>` |
+
+### Available skills
+
+| Skill | Description |
+|-------|-------------|
+| `pachca-profile` | Profile, status, custom fields |
+| `pachca-users` | Employees and tags (groups) |
+| `pachca-chats` | Channels, conversations, members, export |
+| `pachca-messages` | Messages, files, reactions, buttons |
+| `pachca-bots` | Bots, webhooks, unfurling |
+| `pachca-forms` | Interactive forms |
+| `pachca-tasks` | Reminders (tasks) |
+| `pachca-search` | Full-text search |
+| `pachca-security` | Audit events, DLP |
+| `pachca` | Router skill — routes to the right skill |
+
+Skills are generated automatically from the OpenAPI spec on `bun turbo build`. Install only from the official repository — skills contain instructions only (no executable code).
+
+## n8n
+
+A community node for [n8n](https://n8n.io/) — 18 resources, 65+ operations, and a Pachca Trigger with automatic webhook registration.
+
+```bash
+# In n8n: Settings > Community Nodes > n8n-nodes-pachca
+npm install n8n-nodes-pachca
+```
+
+Generated automatically from the OpenAPI spec, fully backward-compatible with v1.
+
+**Docs**: [dev.pachca.com/guides/n8n](https://dev.pachca.com/guides/n8n/overview) · **[README](integrations/n8n/README.md)**
+
+## SDK
+
+| Language | Package | Registry |
+|----------|---------|----------|
+| [TypeScript](sdk/typescript/README.md) | `@pachca/sdk` | npm |
+| [Python](sdk/python/generated/README.md) | `pachca-sdk` | PyPI |
+| [Go](sdk/go/README.md) | `github.com/pachca/go-sdk` | Go modules |
+| [Kotlin](sdk/kotlin/README.md) | `com.pachca:sdk` | JitPack |
+| [Swift](sdk/swift/README.md) | `PachcaSDK` | SPM |
+| [C#](sdk/csharp/generated/README.md) | `Pachca.Sdk` | NuGet |
+
+Every SDK follows one pattern: `PachcaClient(token)` → `client.service.method(request)`.
+
+**Conventions:**
+- **Input**: path params and body fields (if ≤2) are spread into method arguments. Otherwise — a single request object.
+- **Output**: if an API response contains a single `data` field, the SDK returns its contents directly.
+- Service, method, and field names match the operationId and parameters from the OpenAPI spec.
+
+**Example (TypeScript):**
+
+```typescript
+import { PachcaClient } from "@pachca/sdk";
+
+const pachca = new PachcaClient("YOUR_TOKEN");
+const users = await pachca.users.listUsers();
+await pachca.reactions.addReaction(messageId, { code: "👍" }); // ≤2 fields → arguments
+```
+
+SDKs are generated from `openapi.yaml` and published automatically on push to `main`.
+
+### Generator
+
+Instead of a prebuilt SDK, you can generate a typed client straight into your own project:
+
+```bash
+npx @pachca/generator --output ./generated --lang typescript
+npx @pachca/generator --output ./generated --lang typescript,python,go,kotlin,swift,csharp
+```
+
+| Option | Description |
+|--------|-------------|
+| `--spec <path\|url>` | Path or URL to an OpenAPI 3.0 YAML (default: `https://dev.pachca.com/openapi.yaml`) |
+| `--output <dir>` | Output directory for the generated code |
+| `--lang <langs>` | Comma-separated languages: `typescript`, `python`, `go`, `kotlin`, `swift`, `csharp` |
+| `--examples` | Generate `examples.json` with call examples |
+
+**Docs**: https://dev.pachca.com/guides/sdk/overview
+
+## Testing
+
+| Tool | How to use |
+|------|------------|
+| [Scalar](https://client.scalar.com/?url=https://dev.pachca.com/openapi.yaml) | Online client right in the browser — no install |
+| [Postman Collection](https://dev.pachca.com/pachca.postman_collection.json) | Download and import into Postman |
+| Bruno | Download the same file and import: File → Import → Postman Collection |
+
+## AI integrations
+
+| File | Contents |
+|------|----------|
+| [`/llms.txt`](https://dev.pachca.com/llms.txt) | Short index: every endpoint with links + a line map |
+| [`/llms-full.txt`](https://dev.pachca.com/llms-full.txt) | Full docs: guides + endpoints with parameters |
+| [`/llms-en.txt`](https://dev.pachca.com/llms-en.txt) | English version of the full docs (for Context7) |
+| [`/skill.md`](https://dev.pachca.com/skill.md) | AI-agent skill: workflows, capabilities, links |
+| [`/workflows.arazzo.yaml`](https://dev.pachca.com/workflows.arazzo.yaml) | Multi-step API workflows in Arazzo 1.0.1 |
+| `/api/{section}/{action}.md` | A standalone .md for each endpoint and guide |
+| `<any page>.md` | Markdown version of any page (or the `Accept: text/markdown` header) |
+| `/.well-known/agent-skills/index.json` | Agent Skills discovery index (Cloudflare RFC) |
+
+[Context7](https://context7.com/pachca/openapi) — AI-native document discovery. Through the CLI, the API reference is available without the website too: `pachca api ls`, `pachca api <METHOD> <path> --describe`.
+
+All files are served with `Access-Control-Allow-Origin: *`, marked `X-Robots-Tag: noindex`, and cached through a CDN.
+
+## Development
+
+```bash
+bun install
+
+bun turbo dev            # Development with hot reload (localhost:3000)
+bun turbo build          # Production build
+bun turbo check          # All checks (lint + typecheck + knip + format)
+bun turbo generate       # TypeSpec → openapi.yaml + SDK
+```
+
+## Contact
+
+- [GitHub Issues](https://github.com/pachca/openapi/issues)
+- support@pachca.com · team@pachca.com
+
+---
+
+Architecture and maintainer internals are documented in the Russian [README.md](README.md) and in [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/README.md b/README.md
@@ -8,6 +8,8 @@
 [![PyPI](https://img.shields.io/pypi/v/pachca-sdk)](https://pypi.org/project/pachca-sdk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
+> English version: [README.en.md](README.en.md)
+
 Unified Developer Experience Platform для [Pachca API](https://dev.pachca.com) — API корпоративного мессенджера Пачка. Один источник (TypeSpec + workflows.ts + examples.ts) генерирует артефакты для всех каналов: web docs, CLI, SDK, n8n node, agent skills, LLM context.
 
 **Документация**: https://dev.pachca.com · **OpenAPI**: https://dev.pachca.com/openapi.yaml · **Авторизация**: https://dev.pachca.com/api/authorization · **Changelog**: https://dev.pachca.com/updates · **Postman/Bruno**: https://dev.pachca.com/pachca.postman_collection.json

diff --git a/SKILL.md b/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: pachca
+description: >
+  Pachca — корпоративный мессенджер с REST API и CLI. Роутер: определяет нужный
+  скилл для любой задачи, связанной с Pachca. Используй этот скилл, когда
+  пользователь упоминает Pachca, хочет взаимодействовать с API Pachca или
+  нуждается в помощи с любой операцией Pachca. Этот скилл маршрутизирует к нужному
+  под-скиллу. НЕ делай API-вызовы напрямую — направь к нужному скиллу.
+allowed-tools: Bash(npx:*), Bash(pachca:*), Bash(which:*), Bash(npm:*)
+---
+
+# pachca
+
+Pachca — corporate messenger with REST API and CLI.
+
+## Quick start
+
+```bash
+npx -y @pachca/cli <command> --token <TOKEN>
+```
+
+## For regular use
+
+```bash
+npm install -g @pachca/cli && pachca auth login
+```
+
+## Routing
+
+Identify the user task and activate the appropriate skill.
+
+| Task | Skill |
+|------|-------|
+| Pachca — МОЙ профиль, МОЙ статус, кастомные поля | `pachca-profile` |
+| Pachca — информация о текущем OAuth-токене: его скоупы (права доступа), даты создания и последнего использования, тип владельца (пользователь или бот) | `pachca-oauth` |
+| Pachca — управление сотрудниками (участниками пространства) и тегами (группами) | `pachca-users` |
+| Pachca — управление чатами, каналами и беседами | `pachca-chats` |
+| Pachca — сообщения: отправка, редактирование, удаление | `pachca-messages` |
+| Pachca — управление ботами и вебхуки | `pachca-bots` |
+| Pachca — интерактивные формы и модальные окна для ботов | `pachca-forms` |
+| Pachca — задачи и напоминания: создание, список, обновление, выполнение, удаление | `pachca-tasks` |
+| Pachca — полнотекстовый поиск по сотрудникам, чатам и сообщениям | `pachca-search` |
+| Pachca — журнал безопасности: отслеживание входов, действий пользователей, изменений сообщений и нарушений DLP | `pachca-security` |
+
+## CLI commands
+
+Full list: `pachca commands`
+Advanced workflows: references/ in each skill
+Help: `pachca <command> --help`
diff --git a/apps/docs/scripts/skills/generate.ts b/apps/docs/scripts/skills/generate.ts
@@ -194,6 +194,13 @@ export function generateAllSkills(api: ParsedAPI) {
     results.push({ path: `${base}/SKILL.md`, content: routerMd });
   }
 
+  // Root-level entry points for skill catalogs that scan the repository root
+  // rather than recursing into skills/<name>/ (e.g. OpenAgentSkill wants a
+  // skill.json manifest; simpler crawlers look for a top-level SKILL.md). The
+  // recursive registries (skills.sh, GuildSkills) already read skills/*/SKILL.md.
+  results.push({ path: 'SKILL.md', content: routerMd });
+  results.push({ path: 'skill.json', content: generateSkillJson() });
+
   // Agent Skills Discovery RFC v0.2.0 index. Canonical path is
   // /.well-known/agent-skills/index.json; also served at the legacy
   // /.well-known/skills/index.json (Mintlify-style path, referenced by
@@ -695,6 +702,40 @@ function generateRouterSkillMd(): string {
   return lines.join('\n');
 }
 
+/**
+ * Root skill.json manifest for catalogs that require it (OpenAgentSkill).
+ * Distinct from the RFC discovery index — this is a single flat manifest
+ * describing the repository as one publishable skill package. Fields follow
+ * the OpenAgentSkill schema: name, version, description, category, platforms,
+ * author. Version tracks the TypeSpec spec package.
+ */
+function generateSkillJson(): string {
+  let version = '1.0.0';
+  try {
+    const specPkg = JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, 'packages/spec/package.json'), 'utf8')
+    );
+    if (specPkg.version) version = specPkg.version;
+  } catch {
+    // fall back to the default version
+  }
+
+  const manifest = {
+    name: 'pachca',
+    version,
+    description:
+      'Agent skills and CLI for the Pachca corporate messenger REST API — messages, chats, employees, threads, tasks, bots, and webhooks.',
+    category: 'communication',
+    platforms: ['claude-code', 'cursor', 'codex', 'gemini-cli'],
+    author: { name: 'Pachca', github: 'pachca' },
+    homepage: 'https://dev.pachca.com',
+    repository: 'https://github.com/pachca/openapi',
+    license: 'MIT',
+  };
+
+  return JSON.stringify(manifest, null, 2) + '\n';
+}
+
 /**
  * Agent Skills Discovery RFC v0.2.0 index.
  * Schema: https://schemas.agentskills.io/discovery/0.2.0/schema.json
@@ -809,7 +850,7 @@ review generated diffs → commit. Branch from \`origin/main\`; open a PR
 | Generated | Source of truth |
 |-----------|-----------------|
 | \`packages/spec/openapi.yaml\` | \`packages/spec/typespec.tsp\` (then \`npx turbo build --filter=@pachca/spec --force\`) |
-| \`apps/docs/public/llms*.txt\`, \`public/**/*.md\`, \`public/skill.md\`, \`public/.well-known/**\`, \`public/workflows.arazzo.yaml\`, Postman collection | \`apps/docs/scripts/generate-llms.ts\` + \`scripts/skills/\` |
+| \`apps/docs/public/llms*.txt\`, \`public/**/*.md\`, \`public/skill.md\`, \`public/.well-known/**\`, \`public/workflows.arazzo.yaml\`, Postman collection, root \`SKILL.md\` + \`skill.json\` | \`apps/docs/scripts/generate-llms.ts\` + \`scripts/skills/\` |
 | \`packages/cli/src/commands/**\` (except \`auth\`/\`config\`), \`packages/cli/CHANGELOG.md\` | \`packages/cli/scripts/generate-cli.ts\`; \`src/data/changelog.json\` |
 | n8n node files | \`n8n-nodes-pachca\` generator |
 | \`AGENTS.md\` (this file) | \`apps/docs/scripts/skills/generate.ts\` (\`generateAgentsMd()\`) |

diff --git a/skill.json b/skill.json
@@ -0,0 +1,19 @@
+{
+  "name": "pachca",
+  "version": "1.0.0",
+  "description": "Agent skills and CLI for the Pachca corporate messenger REST API — messages, chats, employees, threads, tasks, bots, and webhooks.",
+  "category": "communication",
+  "platforms": [
+    "claude-code",
+    "cursor",
+    "codex",
+    "gemini-cli"
+  ],
+  "author": {
+    "name": "Pachca",
+    "github": "pachca"
+  },
+  "homepage": "https://dev.pachca.com",
+  "repository": "https://github.com/pachca/openapi",
+  "license": "MIT"
+}