docs(skills): add agent skills for the SDK#34
Conversation
Mirrors the b24ui skills layout: a top-level `skills/` directory with `index.json` and a single `b24-jssdk` skill. The skill teaches *when* to use each entry point and method (decision matrices, conventions, recipes); detailed API references live in README-AI.md and the docs site. Structure: - skills/index.json - skills/b24-jssdk/SKILL.md (routing table, install, core rules) - references/api-surface.md (categorized export index) - references/guidelines/ (entry-points, conventions, error-handling, rate-limiting, logger) - references/recipes/ (frame-apps, webhook-server, oauth-apps, batch-calls, list-pagination, ui-integrations, helper-manager, pull-client, nuxt-module)
Skill content was using the deprecated AbstractB24 call*/batch*/list*
methods (scheduled for removal in v2.0.0). Rewrite all recipes,
guidelines, and the API surface index against the current
b24.actions.v{2,3}.{call,callList,fetchList,batch,batchByChunk}.make
managers.
- frame-apps, webhook-server, oauth-apps, batch-calls, list-pagination,
nuxt-module recipes: switch every example to actions.make form.
- conventions, api-surface, error-handling: rewrite the REST surface
section; flag the legacy call* methods explicitly.
- rate-limiting: fix ParamsFactory.getEnterprise() (was wrongly named
getForEnterprise), add getBatchProcessing / getRealtime /
fromTariffPlan, use $b24.setRestrictionManagerParams.
- oauth-apps: spell out the real B24OAuth constructor signature, cover
setCallbackRefreshAuth / setCustomRefreshAuth / RefreshTokenError.
- SKILL.md: update core rules to point at actions managers; note the
README-AI.md deprecation mismatch.
- AGENTS.md: add a "Agent skills" section pointing readers at skills/.
IgorShevchik
force-pushed
the
claude/implement-skills-structure-nBN5h
branch
from
6929ddb to
ed3fe12
Compare
|
Addressed the review's correctness issues (1–3) and the housekeeping points (4–5) in a follow-up commit What changed1. All examples now use
Files rewritten: Added a note to 2. The actual 3. Real
new B24OAuth(authOptions: B24OAuthParams, oAuthSecret: B24OAuthSecret, options?: { restrictionParams?: Partial<RestrictionParams> })Plus coverage of 4. Rebased onto Picked up v1.1.1 + the limiter changes from #32. Force-pushed with 5. Added Still outstanding
Diff: Generated by Claude Code |
README-AI.md had an accurate deprecation banner at the top but every
example below it still used the legacy AbstractB24.call*/batch*/list*
methods scheduled for removal in v2.0.0. AI agents reading the file
would pattern-match the examples, not the banner.
- Replace every example with b24.actions.v{2,3}.{call,callList,
fetchList,batch,batchByChunk}.make({ ... }) form.
- Document all three batch input shapes (tuples, objects, named).
- Add a B24OAuth section: real constructor signature,
setCallbackRefreshAuth, setCustomRefreshAuth, RefreshTokenError.
- Add a rate limiting section pointing at ParamsFactory presets and
$b24.setRestrictionManagerParams.
- Cross-link to skills/b24-jssdk/SKILL.md (the agent-routing companion).
- Fix the broken "// fix" code block and the wrong `import Text from`
default-import.
- Update the export map: drop deprecated call* / paging helpers, add
action option types, RefreshTokenError, ParamsFactory.
Skill back-ports:
- AjaxResult.isMore/getNext/getTotal noted as v2-only in SKILL.md,
conventions.md, and list-pagination.md (v3 has no next/total
envelope; aggregate replaces getTotal).
- Drop stale "README-AI uses deprecated API" notes — no longer true.
|
Pushed Why this change belongs in this PR
Fixing both the skill and its upstream source in one atomic change is better than landing the skill against a doc that still teaches the wrong thing. What changed in
|
Each page in docs/content/docs/2.working-with-the-rest-api/ now points at the matching recipe or guideline in skills/b24-jssdk/. Closes the docs ↔ skill ↔ source triangle suggested in PR #34 review. Mapping: - call (v2, v3) → guidelines/conventions - callList / fetchList → recipes/list-pagination - batch / batchByChunk → recipes/batch-calls - frame, frame-initialize → recipes/frame-apps - frame-dialog/options/parent/placement/slider → recipes/ui-integrations - 66.logger.md → guidelines/logger - 77.limiters.md → guidelines/rate-limiting Pages without prior `links:` block get one; pages with existing links get one new entry appended (so the source link, type links, and MDN references stay primary).
|
Pushed Mapping
19 pages touched, +62/−0. Entries appended to existing Skipped
If you want either of these linked anyway, point me at the target and I'll add it. What's left in this PR
Pre-merge could squash these four into a single commit if you prefer linear history — let me know. Generated by Claude Code |
v2 and v3 are independent endpoints, not old-vs-new. The previous skill text framed v3 as "new code" and v2 as "fall back when v3 doesn't have it"; in practice v3 today supports only tasks.task.* / main.eventlog.* and a few meta endpoints — everything else (CRM, IM, user, profile, placement, options) is v2-only. Restructure: - Add skills/b24-jssdk/references/recipes/rest-api-v2.md — full v2 surface (call, callList, fetchList, batch, batchByChunk) with code. - Add rest-api-v3.md — mirror, leads with the supported method list and a "prefer v2" steer. - Slim batch-calls.md and list-pagination.md to decision pages that point at the v2/v3 examples. - Update conventions.md, api-surface.md, SKILL.md (routing table + core rule #5) to reflect the v2-by-default story. - index.json: add the two new files. Bug fixes (v3.* calls that would throw at runtime): - webhook-server.md: v3.batch.make with crm.item.list -> v2.batch.make. - oauth-apps.md: v3.call.make with user.current -> v2.call.make (x2). - error-handling.md: v3.call.make with crm.item.get and user.current, v3.batch.make with crm.item.list -> v2.*. - README-AI.md: same set of v3->v2 swaps; v3 batch examples retained only where the methods are actually v3-supported. - frame-apps.md: drop the stale per-action bullet list, point at the rest-api-v2/v3 recipes. OAuth corrections (signatures were wrong): - setCallbackRefreshAuth callback signature is ({ authData, b24OAuthParams }) => Promise<void>, not (newAuth) =>. - setCustomRefreshAuth callback takes no args: () => Promise<HandlerRefreshAuth>. - Fill in the real B24OAuthParams / B24OAuthSecret example fields (applicationToken, memberId, expires, scope, status, etc.) per packages/jssdk/src/types/auth.ts. README-AI.md cross-link to the skill changed from a relative path (broken from packages/jssdk/) to the absolute GitHub URL. Docs cross-links retargeted: per-version REST API pages (call, callList, fetchList, batch, batchByChunk × v2/v3) now link to the matching rest-api-v{2,3} recipe instead of the decision pages.
|
Pushed v2/v3 split —
|
| File | Fixed | Was |
|---|---|---|
webhook-server.md:52 |
v2.batch.make |
v3.batch.make with crm.item.list |
oauth-apps.md:42 |
v2.call.make |
v3.call.make with user.current |
oauth-apps.md:79 |
v2.call.make |
v3.call.make with user.current |
error-handling.md:13 |
v2.call.make |
v3.call.make with crm.item.get |
error-handling.md:65 |
v2.batch.make |
v3.batch.make with crm.item.list |
error-handling.md:96 |
v2.call.make |
v3.call.make with user.current |
README-AI.md (webhook section) |
v2.batch.make |
v3.batch.make with crm.item.list |
README-AI.md (OAuth section + error handling) |
v2.call.make |
v3.call.make with user.current / crm.item.get |
Remaining v3 examples (tasks.task.*, main.eventlog.list) confirmed against version-manager.ts to actually be in the v3 supported list.
Reinforced the rule in three places (SKILL.md core rule #5, conventions.md, README-AI.md deprecation banner): default to v2, pick v3 only when the specific method is on the v3 list.
Minor fixes from the review
README-AI.mdcross-link to skill — switched from[skill](../../skills/...)(which doesn't resolve frompackages/jssdk/) to the absolute GitHub URL.B24OAuthconstructor example — was a placeholder comment in bothoauth-apps.mdandREADME-AI.md. Filled in realB24OAuthParams(applicationToken,memberId,accessToken,refreshToken,expires,expiresIn,scope,domain,clientEndpoint,serverEndpoint,status) pertypes/auth.ts.setCallbackRefreshAuth/setCustomRefreshAuthsignatures — I had them wrong. Real shapes (verified againsttypes/auth.ts):CallbackRefreshAuth = (params: { authData: AuthData, b24OAuthParams: B24OAuthParams }) => Promise<void>— was(newAuth) =>.CustomRefreshAuth = () => Promise<HandlerRefreshAuth>— wasasync (currentAuth) =>(takes no args).
- Tasks params — aligned all
tasks.task.getexamples on the SDK's own pattern:{ id: 1, select: ['id', 'title'] }(matches the docstrings inpackages/jssdk/src/core/actions/v3/batch.ts).
Docs cross-link retarget
The per-version REST API docs pages now link to the matching version-specific recipe:
| Docs page(s) | Was → Now |
|---|---|
1.call-rest-api-ver{2,3}.md |
guidelines/conventions.md → recipes/rest-api-v{2,3}.md |
2.call-list-rest-api-ver{2,3}.md |
recipes/list-pagination.md → recipes/rest-api-v{2,3}.md |
2.fetch-list-rest-api-ver{2,3}.md |
recipes/list-pagination.md → recipes/rest-api-v{2,3}.md |
3.batch-rest-api-ver{2,3}.md |
recipes/batch-calls.md → recipes/rest-api-v{2,3}.md |
4.batch-by-chunk-rest-api-ver{2,3}.md |
recipes/batch-calls.md → recipes/rest-api-v{2,3}.md |
More direct — each docs page jumps straight to the skill recipe that covers the same version.
State of the PR
- 5 commits: skills add → v2/v3 API rewrite → README-AI rewrite → docs cross-links → this commit (v2/v3 split + bug fix + minor).
- 40 files total in diff.
Ready for re-review.
Generated by Claude Code
- batch-calls.md / list-pagination.md / conventions.md / api-surface.md:
cross-links into rest-api-v{2,3}.md used Markdown header fragments
(e.g. #batch--batchmake, #when-to-use-v3--and-when-not-to). GitHub's
anchor slugger drops em-dashes and backticks inconsistently, so the
links could break silently. Drop the fragments and point at the file
root + a short pointer to the section by name.
- README-AI.md "Recommended generation patterns" had a stale "for new
code prefer v3" bullet — directly contradicts the v2-default story
added elsewhere in the same commit chain. Replace with text that
matches the v3-method-list rule from the deprecation banner.
Повторное ревью (3-е) + правки в
|
…inks + polish Acts on the review comment from PR #34 author (which is being closed in favour of this one): #38 (comment) 1. AGENTS.md — new "Agent Skills" section listing the 7 skills with a one-line "when to use" table. Without this, a human / 3rd-party agent reading AGENTS.md as the "single source of truth" doesn't discover `.claude/skills/`. 2. .github/contributing/*.md — added an "Agent-facing mirror" reference block at the top of all 4 guides (transports-and-results, package-structure, testing, documentation) pointing at the matching skill files. Makes skill ↔ contributing sync a shared obligation. 3. docs/content/docs/2.working-with-the-rest-api/*.md — added a "Skill — <name>" link entry to frontmatter `links:` of 21 pages (call/callList/fetchList/batch/batchByChunk × {v2,v3}, frame-*, choosing-the-right-method, errors, limiters). Bumped `audited:` to 2026-05-26 because adding the cross-link is the audit. `docs-lint` passes cleanly. 4. Cosmetic — replaced `offClientSideWarning?.()` with `offClientSideWarning()` across all skill files and recipes. The method is present on every concrete entry point; optional chaining created false impression of variability. 5. Recipe 9 — switched the canonical example to `ENTITY_TYPE_ID: 2` (numeric, accepted on every portal version per #34 author's testing) from the symbolic `ENTITY_TYPE: 'deal'`. Comment updated to mention the string fallback. 6. b24jssdk-core SKILL.md — new "Security checklist for event-receiver recipes" section consolidating the application_token + reply-200- first + setCallbackRefreshAuth + HTML-escape guidance that currently only lives in the per-recipe Notes blocks. Skipped from the review: - audited stamps on examples/*.md — reviewer explicitly noted this as "на усмотрение" and `docs:lint-pages` accepts it. - Recipe 7 live-portal payload-shape verification — needs B24_HOOK, documented in REPORT.md as open question.
|
Закрываю в пользу #38 — он содержательно сильнее (компилируемые Ключевые выводы и наработки переехали в виде ревью на #38: #38 (comment) Что предложено подобрать оттуда отдельным маленьким коммитом перед мержем #38:
Ветка Generated by Claude Code |
2 participants
Summary
skills/directory mirroring the layout used inbitrix24/b24ui/skills:index.jsonmanifest + a singleb24-jssdkskill withSKILL.mdandreferences/.packages/jssdk/README-AI.mdand the docs site —SKILL.mdlinks out to them rather than duplicating.README-AI.md,AGENTS.md,CLAUDE.md).Layout:
Test plan
skills/b24-jssdk/SKILL.mdend-to-end — routing table covers expected agent taskspackages/jssdk/README-AI.mdand the source underpackages/jssdk/src/for factual accuracyindex.jsonlists every file underskills/b24-jssdk/(17 entries total when includingSKILL.md+ 16 reference files)Notes for reviewers
A few facts worth a second pair of eyes (flagged here because they were inferred from
README-AI.mdand source-tree shape rather than confirmed line-by-line):references/recipes/oauth-apps.md— theB24OAuthconstructor signature in the example is left as a comment placeholder; if you want the exact args spelled out, please point at the canonical form and I'll fill it in.references/recipes/list-pagination.md— claimsidKey: 'id'(lowercase) forcrm.item.listpayloads vs default'ID'for legacycrm.deal.list-style methods; worth a quick sanity check.references/guidelines/rate-limiting.md— usesParamsFactory.getForEnterprise()as the enterprise preset name; confirm the actual export name.Generated by Claude Code