Imported from makestarlab/makestar-admin-ai-toolkit (opencode/.opencode/skills/makestar-admin-resource-scripts/SKILL.md). Install upstream with npx skills add makestarlab/makestar-admin-ai-toolkit --skill makestar-admin-resource-scripts. Copyright stays with the author (MIT).

Makestar Admin Resource Scripts

Use this skill to run the low-level resource probes without inventing new request shapes.

CLI preflight

Required: makestar-admin >=0.2.17. Cowork/sandboxed Linux agents: before any CLI action, resolve or install the sandbox CLI with the generated package helper (cowork/cowork-cli-bootstrap.sh in AI Toolkit exports, or references/cowork-cli-bootstrap.sh when that helper is bundled next to these instructions), then use the returned executable path and its verification evidence. Do not use host installers inside the sandbox. Host shells: use the normal makestar-admin on PATH and keep macOS Homebrew, Windows winget/MSI, Linux install.sh, or public release archive install guidance available for operator setup. Before the first CLI-dependent action, run makestar-admin --version (or the Cowork helper returned executable with --version), compare it with the required range, then print exactly one status line:

• CLI update required — if the CLI is missing, older than the minimum, or outside the supported range. Agents may attempt exactly one approved automatic install/upgrade for the detected host OS, then rerun makestar-admin --version.
  • macOS host: run brew update && (brew upgrade makestarlab/tap/makestar-admin-cli || brew install makestarlab/tap/makestar-admin-cli).
  • Windows host PowerShell: run winget upgrade --id Makestar.MakestarAdminCLI -e --source winget; if ($LASTEXITCODE -ne 0) { winget install --id Makestar.MakestarAdminCLI -e --source winget }.
  • Linux host: run curl -fsSL https://github.com/makestarlab/makestar-admin-cli-releases/releases/latest/download/install.sh | sh.
  • Cowork/sandboxed Linux: use the generated package helper and its verification evidence, not host package managers. If the approved command needs admin elevation, opens a GUI installer, fails, or still leaves the CLI outside the required range, stop and show the relevant manual setup path: Homebrew on macOS, winget or the public MSI on Windows, or the public release install.sh/archive on Linux.
• skill/plugin update required — if the installed CLI is newer than this skill bundle supports and a newer skill bundle is available. Do not downgrade silently.
• check auth/setup — only when the CLI is in range; then run makestar-admin auth status if the action still fails. Installed skills/plugins do not bundle the CLI binary. Do not require repository fallback or Python-module commands from an installed skill/plugin bundle.

Rules

• Prefer browser-confirmed request shapes.
• Keep admin and OMS resource families separate.
• If response meaning is unclear, inspect frontend first.
• Resource-level output should expose all information actually visible on the corresponding integrated-admin screen by default.
• If a page is composed from multiple connected resources, keep the single-resource script focused and express the combined screen in a composite/page-level skill or contract.
• Use this skill for read-only querying only. Do not use it for create/update/delete flows.
• If a write boundary exists but the task is still read-only, document the boundary source-only and stop there.

Token setup

• Preferred current-session setup starts with shell-neutral login/status commands:
  • makestar-admin auth status
  • makestar-admin auth login
• Stage tokens in the current terminal only, matching the shell the agent is actually using. Git for Windows provides Git Bash, but Windows Claude/Codex sessions may run PowerShell.
  • macOS / Linux / Git Bash: eval "$(makestar-admin auth token --shell)"
  • Windows PowerShell:

    $tokens = makestar-admin auth token --json | ConvertFrom-Json
    $env:MAKESTAR_ADMIN_ADMIN_TOKEN = $tokens.MAKESTAR_ADMIN_ADMIN_TOKEN
    $env:MAKESTAR_ADMIN_OMS_TOKEN = $tokens.MAKESTAR_ADMIN_OMS_TOKEN

  • Plain cmd.exe is not recommended; prefer PowerShell or Git Bash.
• Installed release skill bundles should stop for CLI setup when the integrated CLI is unavailable; do not switch to repository module commands.
• These setup paths populate the env-token contract expected by resource scripts:
  • MAKESTAR_ADMIN_ADMIN_TOKEN
  • MAKESTAR_ADMIN_OMS_TOKEN
• If makestar-admin auth is not logged in or unavailable, load makestar-admin-auth-token for login/status/token handling first.
• Use makestar-admin-browser-token only as the fallback when CLI token acquisition is unavailable or blocked.
• Do not move login, refresh-token storage, or browser inspection logic into individual resource scripts; keep them env-token based and independently testable.

Typical commands

• Prefer the integrated CLI. If the binary/console entrypoint is unavailable, complete the CLI preflight setup before running resource commands.
• makestar-admin products list --size 10
• makestar-admin products list --search <title_product_code_artist_company_or_id> --size 10
• makestar-admin products list --period-type created_at --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> --size 10
• makestar-admin products list --period-type released_at --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> --size 10
• makestar-admin product-events latest --display-status displayed --size 10
• makestar-admin product-events list-by-code --code <event_code>
• makestar-admin product-events detail <event_id>
• makestar-admin product-contents list <product_id>
• makestar-admin skus search --size 10
• makestar-admin skus search --below-safety-quantity-only Y --size 10
  • SKU search summary must keep safetyQuantity 안전재고 separate from vendorPackSize 박스당 수량.
• makestar-admin skus stock-detail <sku_code>
  • pricing questions should be answerable directly from the default summary output
  • summary should include at least price, purchasePrice, taxationYn, vendorName, productionCompanyName
  • distributor deadline questions should be answerable from detail summary fields distributorPreOrderDeadline (유통사 선주문 발주 마감일) and distributorFinalOrderDeadline (유통사 최종 발주 마감일)
• makestar-admin reference-lookups artists --search <artist_name> --limit 10
• makestar-admin reference-lookups manufacturers --search <company_name> --limit 10
• makestar-admin reference-lookups orderers --search <company_name> --limit 10
• makestar-admin reference-lookups sku-categories --search <category_name_or_code> --limit 10
• makestar-admin photocard-skus list --size 10
• makestar-admin photocard-skus statistics --json
• makestar-admin photocard-work-requests list --work-request-status WAITING --size 10
• makestar-admin photocard-sku-opp-work verify --size 1 --json
• makestar-admin orders list --size 10
• makestar-admin orders list --stock-allocation-needed --size 10
• makestar-admin orders detail <order_no>
• makestar-admin orders get --ids <order_no1>,<order_no2>
• makestar-admin purchase-orders list --size 10
• makestar-admin purchase-orders detail <purchase_order_code>
• makestar-admin purchase-requests list --size 10
• makestar-admin purchase-requests detail <purchase_order_request_id>
• makestar-admin advance-ship-notices search --purchase-order-code <purchase_order_code>
• makestar-admin inbounds list --size 10
• makestar-admin inbounds detail --purchase-order-code <po_code> --goods-received-note-id <grn_id>
• makestar-admin user-groups list --size 10
• makestar-admin user-groups detail <group_id> --include-balance
• makestar-admin user-groups members list <group_id>
• makestar-admin user-groups orders list <group_id>
• makestar-admin user-groups deposit-logs list <group_id>

Question patterns -> commands

B2B 업체/담당자 찾기

• "대표 이메일로 B2B 업체 찾기"
  • makestar-admin user-groups list --name-or-email jinroh78@gmail.com --size 10
• "업체명으로 B2B 업체 찾기"
  • makestar-admin user-groups list --company-name 다이브원 --size 10
• "담당자 이름으로 업체 찾기"
  • makestar-admin user-groups list --manager-name 이재원 --size 10
• "오프라인 매장 있는 B2B 업체만"
  • makestar-admin user-groups list --has-offline-store True --size 10
• "등급 A 또는 E 업체만"
  • makestar-admin user-groups list --user-group-grade 4 --user-group-grade 0 --size 10

B2B 업체 상세 / 페이지 분해 조회

• "업체 484 상세 보여줘"
  • makestar-admin user-groups detail 484 --include-balance
• "업체 484 멤버 목록"
  • makestar-admin user-groups members list 484
• "업체 478 주문 활동"
  • makestar-admin user-groups orders list 478
• "업체 477 예치금 로그"
  • makestar-admin user-groups deposit-logs list 477
• "업체 477 예치금 EARN만"
  • makestar-admin user-groups deposit-logs list 477 --log-type EARN
• "업체 477 예치금 로그를 2026-03-31 하루만"
  • makestar-admin user-groups deposit-logs list 477 --start-date 2026-03-31 --end-date 2026-03-31

주문 조회

• "최근 주문 10개"
  • makestar-admin orders list --size 10
• "재고할당 필요한 배송준비전 주문"
  • makestar-admin orders list --stock-allocation-needed --size 10
  • applies order_status=2, product_event_type=product, payment_status=CONFIRMED, and delivery_requested=false
  • keep this read-only; 배송준비완료 상태 변경은 통합어드민에서 운영자가 수행하는 별도 write action
• "주문번호 C260418201844345M1 상세"
  • makestar-admin orders detail C260418201844345M1
• "특정 이벤트 코드 주문만 보고 싶다"
  • makestar-admin orders list --product-event-code P_10103_BBGIRLS_3 --size 10
• "B2B 주문 쪽을 보고 싶다"
  • makestar-admin orders list --b2b --size 10

구매 / 입고 / ASN 조회

• "최근 발주 10개"
  • makestar-admin purchase-orders list --size 10
• "발주서 PO 코드 상세"
  • makestar-admin purchase-orders detail <purchase_order_code>
• "구매요청 목록"
  • makestar-admin purchase-requests list --size 10
• "구매요청 상세"
  • makestar-admin purchase-requests detail <purchase_order_request_id>
• "특정 발주에 연결된 ASN 찾기"
  • makestar-admin advance-ship-notices search --purchase-order-code <purchase_order_code>
• "입고 상세 보기"
  • makestar-admin inbounds detail --purchase-order-code <po_code> --goods-received-note-id <grn_id>

대분류 조회

• "최근 대분류 10개"
  • makestar-admin products list --size 10
• "검색어로 대분류 찾기"
  • makestar-admin products list --search <title_product_code_artist_company_or_id> --size 10
  • search covers title, product code, artist nickname, company name, and numeric product id
• "상품등록일 기준 대분류 찾기"
  • makestar-admin products list --period-type created_at --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> --size 10
• "발매일 기준 대분류 찾기"
  • makestar-admin products list --period-type released_at --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD> --size 10
  • both dates are required; use pagination.count as the global total and current row length as page count
  • 대분류 is product; 상품 is product_event

SKU / 포토카드 OPP / 이벤트 조회

• "최근 SKU 검색 10개"
  • makestar-admin skus search --size 10
• "안전재고 이하 SKU만"
  • makestar-admin skus search --below-safety-quantity-only Y --size 10
  • output should include availableQuantity, safetyQuantity, and vendorPackSize as distinct columns
• "SKU022138 재고/가격 상세"
  • makestar-admin skus stock-detail SKU022138
  • default summary should include price, purchasePrice, firstWeekClosingDate, distributorPreOrderDeadline, and distributorFinalOrderDeadline when present
• "포토카드 SKU OPP 요청 관리 목록"
  • makestar-admin photocard-skus list --size 10
• "포토카드 SKU OPP 입고~작업 관리 카운터"
  • makestar-admin photocard-skus statistics --json
• "포토카드 OPP 작업 대기 목록"
  • makestar-admin photocard-work-requests list --work-request-status WAITING --size 10
• "포토카드 SKU OPP 화면 API 묶음 검증"
  • makestar-admin photocard-sku-opp-work verify --size 1 --json
  • covers the 요청 관리 tab plus the 입고~작업 관리 statistics, inspection, and work-request list probes.
• "최신 이벤트 목록"
  • makestar-admin product-events latest --display-status displayed --size 10
• "2026-05-17에 판매 종료되는 상품/이벤트 검색"
  • makestar-admin product-events latest --period-type sales_end_at --end-date 2026-05-17 --size 10
  • period_type must use API contract snake_case values (all, created_at, sales_start_at, sales_end_at); do not pass camelCase UI/model keys such as salesEnd.
• "이벤트 코드로 조회"
  • makestar-admin product-events list-by-code --code <event_code>
• "이벤트 상세"
  • makestar-admin product-events detail <event_id>
• "상품 콘텐츠 목록"
  • makestar-admin product-contents list <product_id>

등록 기준정보 조회

• "아티스트 후보 찾기"
  • makestar-admin reference-lookups artists --search <artist_name> --limit 10
  • searches every localized name and shows Korean-compatible artistName plus artistNameEn, artistNameJa, and artistNameZh
• "SKU 유통사 후보 찾기"
  • makestar-admin reference-lookups manufacturers --search <company_name> --limit 10
  • fetches the V2 company list with role=MANUFACTURER; one company row includes Korean-compatible companyName plus companyNameEn, companyNameJa, and companyNameZh; the selected id maps to SKU productionCompanyId
• "SKU 발주처 후보 찾기"
  • makestar-admin reference-lookups orderers --search <company_name> --limit 10
  • fetches the V2 company list with role=ORDERER; one company row includes Korean-compatible companyName plus companyNameEn, companyNameJa, and companyNameZh; the selected id maps to SKU vendorId
• For artist/company lookups, --search matches every value in the multilingual name map and --raw preserves that map (i18n_name or i18nName).
• "SKU 카테고리 후보와 기본 규격 찾기"
  • makestar-admin reference-lookups sku-categories --search <category_name_or_code> --limit 10
  • this is the OMS SKU type/category metadata used to prefill dimensions, volume, HS code, and customs description; it is not 대분류(product) or a display category

Reusable findings

• Makestar terms are intentionally distinct: 대분류 = product, 상품 = product_event, and SKU category = OMS type/category defaults. Do not substitute one route for another.
• The product list response exposes the global total at pagination.count; a default page has 10 rows but that is not the total.
• Product period values are created_at and released_at, and the backend applies them only when both dates are present.
• /user-group/{id} is a composite page contract, not a single API. In practice it is backed by:
  • retrieve_user_group
  • list_user_group_member
  • list_user_group_order
  • deposits/balance
  • and, once the modal opens, deposits
• For B2B deposit flows, distinguish the read-only pieces from write boundaries:
  • read: balance + deposit logs
  • write boundary: deposit-log note PATCH exists, but the current detail dialog is row-backed from the logs list rather than a separate read-detail endpoint
• For B2B member/group searches:
  • search is broad simple search
  • company_name behaves like partial text
  • name_or_email is high-precision
  • manager_name currently behaves closer to exact/high-precision than broad substring partial
  • user_group_grade works with repeated query keys, not bracket-style array encoding

Notes

• Reference lookup --search and --limit are local presentation filters applied after the GET response. Use --raw when the complete unfiltered API response is required.
• Keep company lookup semantics distinct: manufacturers is SKU 유통사 (role=MANUFACTURER, productionCompanyId), while orderers is SKU 발주처 (role=ORDERER, vendorId). Neither command is the unfiltered company selector used by 대분류 registration.
• reference-lookups sku-categories means the OMS SKU type/category and its default dimensional/customs metadata. It is not Makestar 대분류(product) and not a B2C/B2B display category.
• For SKU search, safetyQuantity is 안전재고 and vendorPackSize is 박스당 수량. Do not use vendorPackSize as a fallback for 안전재고.
• The live SKU detail response can expose at least two price-like fields:
  • purchasePrice = 매입가 / cost-side price
  • price = general price field exposed by SKU detail
• The live SKU detail response can expose distributor order deadline fields:
  • distributorPreOrderDeadline = 유통사 선주문 발주 마감일 / Distributor pre-order deadline
  • distributorFinalOrderDeadline = 유통사 최종 발주 마감일 / Distributor final order deadline
  • Current live SKU search/list responses do not expose these fields; use skus stock-detail for them.
• The live regression harness treats this as API drift: raw detail resData.skuInfo must contain both distributor deadline keys, while sampled raw search/list resData.skuList[] rows must not contain them. lastOrderClosingDate is legacy DB-mirror documentation only, not a current live API field requirement.
• If the current skus_stock_detail script summary does not print both values, inspect the raw response or query the endpoint directly with the current browser-derived token.
• When the shell token is missing, load makestar-admin-auth-token and stage env vars with the Bash/Git Bash or PowerShell command from that skill; use browser XHR/fetch extraction only as fallback.

References

• references/scripts.md
• references/question-patterns.md
• references/photocard-opp.md — 포토카드 SKU OPP 요청 관리 / 입고~작업 관리 read-only scripts, page-level verifier, regression rows, and pitfalls.