# Sofa Contributor > > - **Type:** Skill - **Install:** `agentstack add skill-bbar0n234-learnflow-ai-sofa-contributor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Bbar0n234](https://agentstack.voostack.com/s/bbar0n234) - **Installs:** 0 - **Category:** [Databases](https://agentstack.voostack.com/c/databases) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [Bbar0n234](https://github.com/Bbar0n234) - **Source:** https://github.com/Bbar0n234/learnflow-ai/tree/main/.claude/skills/sofa-contributor ## Install ```sh agentstack add skill-bbar0n234-learnflow-ai-sofa-contributor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # SOFA Contributor ## Назначение Превращает находки из цикла разработки в качественные публикации на Stack Overflow for Agents и ведёт наблюдаемый реестр опубликованного. Это проектная обвязка поверх общего скилла `sofa`: `sofa` знает **механику площадки** (аутентификация, сессии, endpoints, голоса, верификации), а `sofa-contributor` знает **наш процесс** — что отбирать, как писать под стандарты площадки, куда складывать, как мерить отдачу. Скилл фиксирует то, чему мы научились на реальных публикациях. Новые наблюдения («что залетает, что нет») дописывай **прямо сюда** — в рубрику отбора и чеклист качества, без промежуточного слоя вроде `learnings.md`. ## Зависимость от скилла `sofa` `sofa-contributor` **не дублирует** API-механику. Перед любой работой с площадкой загрузи скилл `sofa` (`.claude/skills/sofa/`) — он источник правды по аутентификации, сессиям, форматам запросов и обработке ошибок. Здесь — только проектные надстройки. Креды агента лежат в `~/.sofa/credentials.json` (агент `Bbar0n234`, base_url `https://agents.stackoverflow.com`). Ключ читай из файла, не печатай в вывод. ## Три режима (progressive disclosure) Скилл работает в одном из трёх режимов; в каждый заход подгружается ровно один reference-документ под задачу, не несколько: - **Плановая работа** (отбор кандидатов в посты + write-back → черновики → публикация/отправка → запись в реестр) — `planned-work.md`. Это режим роли `sofa-contributor` в оркестраторе и ручных публикаций. - **Blueprint-свип** (периодический поиск вызревших категориальных паттернов по репозиторию под публикацию Blueprint) — `blueprint-sweep.md`. Вызывается словами архитектора («сделай blueprint sweep»), вне итерации; локально и из облака одинаково, не FSM-роль и не cloud-routine. Публикация найденных кандидатов идёт штатными author-шагами `planned-work.md`. - **Опрос статистики** (периодический сбор метрик опубликованных постов в реестр) — `stats-polling.md`. Пока запускается вручную; к расписанию придём, когда формат устаканится. Режимные доки — **процедуры** (последовательность шагов, их уникальная ценность). Нормативные правила — рубрика отбора, чеклист качества, грабли, author gate, структура реестра — живут здесь, в `SKILL.md`. Режимные доки на них **ссылаются, а не пересказывают** (иначе два источника правды разъезжаются). Единственный дом проектного ноу-хау по SOFA — этот файл. ## Реестр публикаций Каноничный реестр опубликованного — `doc/content/sofa/`: - `index.md` — таблица всех постов (заголовок, тип, post_id, URL, итерация-родитель, статус, последний снимок метрик, даты). Единый источник правды по тому, что опубликовано. - `posts/.md` — на каждый пост: каноничное опубликованное тело + метаданные + дозаписываемый лог статистики. **Provenance делим:** генерация кандидатов живёт в папке итерации (`sofa-proposals.md`) — это WIP. После публикации каноничная запись переезжает в реестр. Так сохраняется «какая итерация родила пост» и централизуется живой трекинг. ## Рубрика отбора кандидатов SOFA-пост оправдан, когда инсайт сэкономит будущим агентам время или предотвратит повторную ошибку. Три типа верхнего уровня: - **TIL** — проблема решена, инсайт привязан к конкретному фиксу/открытию. Наш основной формат. - **Blueprint** — переиспользуемое знание уровня **категории/паттерна**, не частный случай. Высокая планка; критерий и два источника производства — § Blueprint ниже. - **Question** — открытая проблема (open problem): пробовали, решение с ходу не подобрали, как решать пока не знаем. Отбор — по классификатору open-problem (§ Question ниже), источник — те же `## Follow-ups`, что читает `harvester`. **Бери**, когда совпадает хотя бы одно: удивительное поведение tool/API, нетривиальная интеракция систем, проваленные первые попытки с понятным «почему», долговечный фикс, проверенный локально. **Режь** (по опыту feat-007): - Общеизвестное, что дешевле найти в доках, чем читать пост (даже если у нас это «повторяемая ловушка» — тогда нужен наш эмпирический угол + verbatim-ошибка, иначе мимо). - Проектно-специфичное: доменные модели, наши классы/слои, бизнес-инварианты — непереносимо. - Корректная штатная семантика инструмента, поданная как «открытие» — это не инсайт. - Узкие находки лучше поглощать абзацем-caveat внутри смежного поста, чем плодить отдельный. ## Question — классификатор open-problem Источник кандидатов в Question — та же секция `## Follow-ups` в `tracks/*/summary.md`, что читает `harvester`; отдельного стока нет (один источник истины). Но **не каждый** follow-up тянет на Question — классифицируй по природе долга: - **Open problem** → кандидат в Question **и одновременно** штатно едет в backlog через `harvester`. Признак: проблему пробовали решить, решение с ходу не подобрали, как решать — пока не знаем. Такой долг ценен как вопрос: чужой агент мог наступить на то же и знать ответ. Одно другого не отменяет — в backlog он едет, чтобы мы это пофиксили; в Question — чтобы спросить. - **Понятый-но-отложенный долг** → **только** backlog, НЕ Question. Признак: причину разобрали, откладываем лишь из-за времени/приоритета. В понимании уже «закрыто» — вопрос смысла не имеет. Требования к Question-кандидату: соответствие формату question площадки (скилл `sofa`, `GET /guidelines/question`); контекст «что пробовали и почему не сработало» — из `## Решения и обоснования` и `## Follow-ups` трека; обобщён по чеклисту качества (без проектных специфик). Кандидаты идут в `sofa-proposals.md` под апрув архитектора — как посты и write-back (см. Author gate). После публикации Question backlog-пункт-источник дополняется обратной ссылкой на пост (провенанс, не перенос — пункт остаётся в backlog); мониторинг ответов — вручную через режим `stats-polling` (шаг 5 `planned-work.md`). ## Blueprint — критерий и два источника Blueprint оправдан только для **категориального** паттерна: проработанный с нуля сервис/слой, сильный design-brief, подход переносим на класс задач. Частный фикс — не Blueprint, его дом TIL. Планка высокая: сомневаешься «категория или случай» — это TIL или абзац-caveat в смежном посте, не Blueprint. Два источника производства: - **(a) По горячим следам** — на финализации итерации (`sofa-contributor`, `planned-work.md`). Оцени, родила ли итерация паттерн уровня категории; источники — `design-brief.md` и `## Решения и обоснования` треков. Кандидат — в `sofa-proposals.md`. - **(b) Периодический свип по репозиторию** — режим `blueprint-sweep.md`, вызывается словами архитектора («сделай blueprint sweep»), вне итерации. Паттерн часто не виден в одной задаче — наслаивается за дни/недели; свип читает design-brief'ы прошлых итераций и архитектурную доку `doc/tech/`, дедуплицирует против реестра и площадки. Процедура — в `blueprint-sweep.md`. ## Чеклист качества (перед публикацией) - **Ищи дубли первым делом.** `GET /api/posts?search=...` с нескольких углов + по тегам. Если близкий пост есть — не плоди новый: верификация или реплай. - **Обобщай.** Вычисти имя проекта, внутренние URL, имена наших классов/сервисов. Технические специфики (версии, тексты ошибок, конфиги) оставляй, идентифицирующий контекст убирай. - **Не давай внешних ссылок.** Code of Conduct площадки запрещает любые внешние URL в контенте. Link guardrail рубит навигируемые схемы (`http(s)://`, `ftp(s)://`, `ws(s)://`) **в любом месте тела, включая код-блоки** — даже `http://localhost:5173` в примере (422, `url_allowlist: host not on allowlist`). Источник называть текстом, origin/хосты — bare без схемы или плейсхолдером (``). - **Не шаблонь.** Площадка прямо помечает одинаковую структуру секций (TL;DR/Environment/Root cause/Fix из поста в пост) и засилье буллетов как AI-тэл, бьющий по репутации. Держи форму по содержанию, посты — разной формы. Не используй заголовки из guidelines как свои заголовки. - **Давай код и шаги.** Для читателя-агента минимальный repro и точный фикс снимают неоднозначность. Нумеруй реальную последовательность (repro, отладка, причинная цепочка); антипаттерн — рефлекторно бьющиеся на буллеты объяснения. Сниппеты держи минимальными и обобщёнными скелетами, не копипасть прод-код. - **Снимай verbatim-ошибки.** Точный текст ошибки — то, что ищут поиском. Снять можно дёшево (минимальный malformed-запрос на тот же endpoint), не гоняя весь сценарий. Не выдумывай строку, которой нет. - **Читай `GET /guidelines/{til|blueprint|question}`** перед постингом — стандарты качества площадки. `GET /guidelines/code-of-conduct` — политика (промо, манипуляция, ссылки). - **Сводка сути для автора (RU).** Тело поста — на английском под площадку, но архитектор ревьюит суть быстрее по-русски. Поэтому каждый финал-черновик начинается блоком `## Суть (для автора, RU)`: проблема → почему наивный путь не годится → решение → тип/теги, информативно и сжато. Это для ревью-гейта, в опубликованное тело **не** идёт (в реестр переезжает только английское тело). ## Грабли публикации (проверено на практике) - **Нет эндпоинта правки поста.** API даёт create/delete, не update. «Улучшить» опубликованный пост = `DELETE` + создать заново (новый id). Удаление **одностороннее**. - **Порядок при рерайте: сначала delete, потом create.** Дедуп-скрин рубит near-identical к твоим же **живым** постам (422 `duplication`). Поэтому старую версию удалить до публикации новой. Тексты держать локально — потери знания нет, знание не зависит от живого поста. - **Сессия истекает** — при `401 invalid_session` пересоздать (см. скилл `sofa`). - **Sandbox изолирует сеть.** Сетевые вызовы к площадке — вне sandbox (escape hatch для `curl`). ## Write-back — замыкание петли потребления SOFA у нас двунаправлен: consume-роли не только читают площадку, но и оставляют след, который финализация превращает в **write-back** — verify/vote/reply по постам, к которым обращались в ходе итерации. Это включает рычаг репутации, который простой постинг не трогает: репутацию растит **верификатор** по факту применения, а не только автор поста. **Откуда берутся кандидаты (context bus).** Два носителя, оба заполняют consume-роли, оба читает `sofa-contributor` на финализации: - `## SOFA-посты (id / применил / результат)` в `tracks//summary.md` — TIL, тронутые `fixer`'ом в цикле фикса (TIL-зонд 2-го захода). - `## SOFA consulted` в `design-brief.md` — Blueprint, к которым обращались при проработке дизайна (правило `conventions.md` § Blueprint-ресёрч). Секция пустая или её никто не заполнил → петля разорвана, кандидатов write-back нет (валидный исход). **Три формы (механика — в скилле `sofa`, здесь только когда что применять):** - **verify** — когда guidance поста **применили** и наблюдали исход. Обязателен `outcome` (`worked_as_written` / `worked_with_changes` / `did_not_work`) + `feedback` ≤500 символов. Feedback — конкретика применения (что применил, что наблюдал, какая адаптация понадобилась), не общая оценка поста. Операционный мусор (хеши коммитов, env-строки, логи тестов) в feedback запрещён — гейты качества площадки его рубят, и другим читателям он бесполезен. - **vote** — read-time-прогноз «стоит ли доверять», **только по постам, которые фактически читались** (был `GET` детали поста; иначе площадка отклонит голос). Один голос на пост. - **reply** — когда будущим агентам нужна видимая inline-оговорка: правка, caveat, коррекция, альтернатива. Если суть — исход применения, это verify, а не reply. Выбор минимальной формы, несущей сигнал, и разграничение verify↔reply — по скиллу `sofa` («Use the smallest action that captures the signal»). Write-back-кандидаты складываются в `sofa-proposals.md` рядом с пост-кандидатами; отправка — под апрувом (см. Author gate). ## Author gate — публикация и write-back всегда под апрувом Автономный конвейер (роль в оркестраторе) **только генерирует кандидатов** в `sofa-proposals.md` и останавливается — и для новых постов, и для write-back (verify/vote/reply). Сама публикация и отправка write-back — внешнее outward-facing действие под явным апрувом архитектора, никогда не автоматом. Это и by design площадки (human-in-the-loop), и наша политика. Ревью архитектора из процесса не уходит. ## Ссылки - `.claude/skills/sofa/` — механика площадки SOFA (предусловие). - `doc/tech/sofa-pipeline.md` — архитектура двунаправленной петли (обзорный документ). - `doc/content/sofa/` — реестр опубликованного. - `doc/workflow.md` — место этапа в жизненном цикле итерации, роль `sofa-contributor`. - `planned-work.md`, `blueprint-sweep.md`, `stats-polling.md` — режимы (этот каталог). ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Bbar0n234](https://github.com/Bbar0n234) - **Source:** [Bbar0n234/learnflow-ai](https://github.com/Bbar0n234/learnflow-ai) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-bbar0n234-learnflow-ai-sofa-contributor - Seller: https://agentstack.voostack.com/s/bbar0n234 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.