Clawhub-skills kintone-agent

Build, query, and automate Cybozu kintone apps — Japan's leading no-code business platform

install

source · Clone the upstream repo

git clone https://github.com/traygerbig/clawhub-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/traygerbig/clawhub-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/business-ops-pack/kintone-agent" ~/.claude/skills/traygerbig-clawhub-skills-kintone-agent && rm -rf "$T"

manifest: business-ops-pack/kintone-agent/SKILL.md

source content

╔═══════════════════════════════════════════════════╗
║  ┌───────────────────────────────────────────┐    ║
║  │  K I N T O N E   A G E N T               │    ║
║  │     ━━━━━━━━━━━━━━━━━━━━━━                │    ║
║  │  🔧 Apps → Records → Workflow → Bulk     │    ║
║  │     Cybozu No-Code Platform CLI           │    ║
║  └───────────────────────────────────────────┘    ║
╚═══════════════════════════════════════════════════╝

kintone

cybozu

no-code

business-apps

workflow-engine

Turn kintone into a programmable powerhouse -- query records, build apps, and automate workflows from the command line at the speed of thought.

Overview

kintone Agent bridges the gap between Cybozu kintone's intuitive no-code interface and the power-user demands of developers, system integrators, and IT administrators who need programmatic control over their business applications. kintone is the dominant no-code/low-code platform in Japan, deployed across enterprises of every scale -- from three-person startups tracking inventory to multinational corporations running complex approval workflows across dozens of departments. This skill gives you direct, scriptable access to the full kintone REST API, enabling operations that would take hundreds of clicks through the GUI to be executed in a single command.

The agent supports the complete spectrum of kintone operations: creating and modifying apps and their field schemas, performing CRUD on records with complex query syntax, managing custom views and layouts, triggering and monitoring process management (workflow) transitions, handling file attachments, administering users and spaces, and even scaffolding plugin development. Bulk operations are first-class citizens -- import thousands of records from CSV, export filtered datasets for analysis, or update fields across millions of records using kintone's native bulk API endpoints. The agent understands kintone's unique query language and translates natural expressions into valid queries, making ad-hoc data exploration seamless.

Architecture:

  ┌──────────────────────────────────────────────────────────┐
  │                    kintone Agent CLI                      │
  │                                                          │
  │  ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐  │
  │  │  Apps   │ │ Records │ │ Workflow │ │    Bulk      │  │
  │  │ Manager │ │  Engine │ │  Engine  │ │  Processor   │  │
  │  └────┬────┘ └────┬────┘ └────┬─────┘ └──────┬───────┘  │
  │       │           │           │               │          │
  │  ┌────▼───────────▼───────────▼───────────────▼────────┐ │
  │  │            Query Builder & Validator                 │ │
  │  │    (kintone query syntax ↔ natural language)         │ │
  │  └──────────────────────┬──────────────────────────────┘ │
  │                         │                                │
  │  ┌──────────────────────▼──────────────────────────────┐ │
  │  │       Auth Layer (API Token / Password / OAuth)      │ │
  │  └──────────────────────┬──────────────────────────────┘ │
  └─────────────────────────┼────────────────────────────────┘
                            │ HTTPS
                            ▼
               ┌─────────────────────────┐
               │   {subdomain}.cybozu.com │
               │     kintone REST API     │
               └─────────────────────────┘

System Prompt Instructions

You are the kintone Agent, a specialist in Cybozu kintone platform automation. Follow these rules precisely:

Authenticate using API tokens (
```
X-Cybozu-API-Token
```
header) by default. Support password authentication (
```
X-Cybozu-Authorization
```
, Base64-encoded) and OAuth as alternatives.
All API requests target
```
https://{KINTONE_DOMAIN}/k/v1/
```
. Validate the domain format before making requests; it must end with
```
.cybozu.com
```
or
```
.kintone.com
```
.
Construct kintone query strings using proper syntax: field codes in backtick-like notation, operators (
```
=
```
,
```
!=
```
,
```
>
```
,
```
<
```
,
```
>=
```
,
```
<=
```
,
```
in
```
,
```
not in
```
,
```
like
```
,
```
not like
```
), and combinators (
```
and
```
,
```
or
```
). Always validate query syntax before execution.

Handle kintone's unique field types correctly:

SINGLE_LINE_TEXT

MULTI_LINE_TEXT

NUMBER

CALC

RICH_TEXT

CHECK_BOX

RADIO_BUTTON

DROP_DOWN

MULTI_SELECT

DATE

TIME

DATETIME

FILE

LINK

USER_SELECT

ORGANIZATION_SELECT

GROUP_SELECT

SUBTABLE

RECORD_NUMBER

CREATOR

MODIFIER

CREATED_TIME

UPDATED_TIME

STATUS

STATUS_ASSIGNEE

CATEGORY

For record creation and updates, validate field values against their field type. Reject invalid data before making API calls (e.g., non-numeric values for NUMBER fields).
Bulk operations must use the
```
/records.json
```
endpoint with arrays. Maximum 100 records per POST/PUT request, 500 record IDs per DELETE request. Chunk automatically for larger datasets.
When exporting data, default to CSV format. Support JSON, TSV, and Excel formats. Include header row with field labels (not field codes) by default.
App deployment requires two steps: first update the preview (
```
/preview/app.json
```
), then deploy (
```
/preview/app/deploy.json
```
). Always confirm deployment status before reporting success.
File operations use the
```
/file.json
```
endpoint. Upload returns a
```
fileKey
```
that must be used within the same transaction to attach to a record.
Process management (workflow) operations must respect the current status. Only valid transitions from the current status are permitted. Use
```
/record/status.json
```
for transitions.
Space and thread operations target
```
/space.json
```
and
```
/space/thread.json
```
. Guest spaces have separate endpoints under
```
/guest/{spaceId}/
```
.
When creating or modifying apps, always preview changes first and require explicit confirmation before deploying to production.
Respect kintone's field code naming convention: alphanumeric characters and underscores only, starting with a letter. Auto-generate valid codes from Japanese field labels using romanization.
Handle kintone's revision system: include
```
revision
```
in updates to prevent concurrent modification conflicts. On conflict (HTTP 409), report the current revision and prompt for resolution.
Support lookup fields by resolving related app references. When a field is a lookup, fetch and display the source record's display field.
Rate limit awareness: kintone has a concurrent connection limit per domain (typically 10). Queue requests and process with appropriate concurrency.
For plugin development scaffolding, generate the
```
manifest.json
```
,
```
config.json
```
, and directory structure per Cybozu's plugin specification.
Always display record numbers with the app identifier prefix for clarity (e.g.,
```
APP-42 #1234
```
).

Environment Variables

Variable	Required	Default	Description
`KINTONE_DOMAIN`	Yes	-	Your kintone subdomain (e.g., `mycompany.cybozu.com` )
`KINTONE_API_TOKEN`	Yes	-	API token generated from app settings (can be comma-separated for multi-app access)
`KINTONE_USERNAME`	No	-	Login username for password-based authentication (alternative to API token)
`KINTONE_PASSWORD`	No	-	Login password (used with `KINTONE_USERNAME` , Base64-encoded in transit)
`KINTONE_GUEST_SPACE_ID`	No	-	Guest space ID for accessing guest space apps
`KINTONE_OUTPUT_FORMAT`	No	`table`	Default output format: `table` , `json` , `csv`
`KINTONE_CONCURRENCY`	No	`5`	Maximum concurrent API connections (max 10 per domain)

Commands

kt apps

List all accessible kintone apps.

$ kt apps

  App ID  Name                      Creator        Records  Updated
  ──────  ────────────────────────  ─────────────  ───────  ────────────
  1       顧客管理                   石原 達也      12,847   2026-03-01
  5       案件管理                   佐藤 花子      3,291    2026-02-28
  12      日報アプリ                 田中 太郎      45,102   2026-03-01
  18      経費申請                   山田 次郎      8,553    2026-02-27
  24      在庫管理                   鈴木 一郎      1,205    2026-03-01
  31      採用管理                   高橋 美咲      423      2026-02-25

  Total: 6 apps accessible with current token

kt records

Fetch records from an app with optional query filtering.

$ kt records --app 1 --query "会社名 like \"Tech\" and ステータス in (\"商談中\", \"提案済\")" --limit 5

  #      会社名              担当者      ステータス  売上見込     最終連絡
  ─────  ──────────────────  ──────────  ──────────  ──────────  ──────────
  #1042  Tech Solutions      石原 達也   商談中      ¥5,400,000  2026-02-28
  #1089  TechBridge Corp     佐藤 花子   提案済      ¥3,200,000  2026-02-25
  #1134  NextTech Inc.       石原 達也   商談中      ¥8,100,000  2026-03-01
  #1201  TechForward Ltd.    田中 太郎   提案済      ¥1,800,000  2026-02-20
  #1256  GreenTech Japan     山田 次郎   商談中      ¥4,500,000  2026-02-27

  Showing 5 of 23 matching records (App: 顧客管理)

kt create

Create a new record in an app.

$ kt create --app 1 --data '{"会社名": "New Startup Inc.", "担当者": "石原 達也", "ステータス": "初回接触", "電話番号": "03-1234-5678"}'

  Record created successfully
  App:        顧客管理 (App ID: 1)
  Record:     #12848
  Revision:   1
  Fields set: 会社名, 担当者, ステータス, 電話番号
  Timestamp:  2026-03-01 15:22:10 JST

kt update

Update an existing record.

$ kt update --app 1 --id 1042 --data '{"ステータス": "受注", "売上見込": 5800000}'

  Record updated successfully
  App:        顧客管理 (App ID: 1)
  Record:     #1042
  Revision:   14 → 15
  Changed:    ステータス (商談中 → 受注), 売上見込 (¥5,400,000 → ¥5,800,000)
  Timestamp:  2026-03-01 15:25:33 JST

kt search

Search across multiple apps with natural language.

$ kt search "overdue tasks assigned to Ishihara" --apps 5,12

  App: 案件管理 (ID: 5) — 3 matches
  #301  サーバー移行プロジェクト   期限: 2026-02-20  ステータス: 進行中
  #445  API連携開発                期限: 2026-02-25  ステータス: 進行中
  #512  セキュリティ監査対応       期限: 2026-02-28  ステータス: 進行中

  App: 日報アプリ (ID: 12) — 0 matches

  Total: 3 overdue records across 2 apps

kt bulk

Perform bulk operations on records.

$ kt bulk --app 1 --action update --query "ステータス = \"初回接触\" and 最終連絡 < \"2025-12-01\"" \
    --set '{"ステータス": "休眠"}'

  Bulk update preview:
  App:         顧客管理 (App ID: 1)
  Matching:    847 records
  Action:      Set ステータス → "休眠"

  Proceed? [y/N]: y

  Processing: [████████████████████████████████████████] 847/847

  Bulk update complete
  Updated:  847 records
  Failed:   0 records
  Duration: 12.3 seconds (9 API calls)

kt fields

Inspect the field schema of an app.

$ kt fields --app 1

  Field Code       Label         Type              Required  Unique
  ───────────────  ────────────  ────────────────  ────────  ──────
  会社名           会社名        SINGLE_LINE_TEXT  Yes       Yes
  担当者           担当者        USER_SELECT       Yes       No
  ステータス       ステータス    DROP_DOWN         Yes       No
  電話番号         電話番号      SINGLE_LINE_TEXT  No        No
  売上見込         売上見込      NUMBER            No        No
  最終連絡         最終連絡      DATE              No        No
  添付ファイル     添付ファイル  FILE              No        No
  備考             備考          MULTI_LINE_TEXT   No        No

  Total: 8 fields (+3 system fields: Record number, Creator, Updated)

kt export

Export records to a file.

$ kt export --app 1 --format csv --query "ステータス != \"休眠\"" --output ./customers_active.csv

  Exporting records from 顧客管理 (App ID: 1)
  Query:    ステータス != "休眠"
  Format:   CSV (UTF-8 with BOM for Excel compatibility)
  Records:  12,000 matching

  Downloading: [████████████████████████████████████████] 12,000/12,000

  Export complete
  File:     ./customers_active.csv
  Size:     4.2 MB
  Records:  12,000
  Columns:  8 fields + Record number

kt import

Import records from a file.

$ kt import --app 1 --file ./new_customers.csv --mode insert

  Import preview:
  App:        顧客管理 (App ID: 1)
  File:       ./new_customers.csv
  Mode:       Insert (new records only)
  Records:    250
  Validation: All 250 records pass schema validation

  Proceed? [y/N]: y

  Importing: [████████████████████████████████████████] 250/250

  Import complete
  Inserted: 250 records (#12849 - #13098)
  Skipped:  0
  Errors:   0

kt workflow

Manage process management (workflow) transitions.

$ kt workflow --app 5 --id 301 --action "承認"

  Workflow transition executed
  App:        案件管理 (App ID: 5)
  Record:     #301 (サーバー移行プロジェクト)
  Action:     承認
  Previous:   レビュー待ち → Assignee: 石原 達也
  Current:    承認済み → Assignee: 佐藤 花子
  Revision:   22 → 23
  Timestamp:  2026-03-01 16:05:44 JST

Workflow

  Developer                  kintone Agent                kintone API
  ─────────                  ─────────────                ───────────
      │                            │                           │
      │  kt records --app 1       │                           │
      │  --query "status=active"   │                           │
      ├───────────────────────────►│                           │
      │                            │  Parse & validate query   │
      │                            │  Translate field names     │
      │                            │                           │
      │                            │  GET /k/v1/records.json   │
      │                            ├──────────────────────────►│
      │                            │  {records: [...], total}  │
      │                            │◄──────────────────────────┤
      │                            │                           │
      │                            │  More pages? Auto-fetch   │
      │                            ├──────────────────────────►│
      │                            │◄──────────────────────────┤
      │                            │                           │
      │  Formatted table output    │  Merge & format results   │
      │◄───────────────────────────┤                           │
      │                            │                           │
      │  kt bulk --action update   │                           │
      ├───────────────────────────►│                           │
      │                            │  Count matching records   │
      │  "847 records. Proceed?"   │  Show preview             │
      │◄───────────────────────────┤                           │
      │  y                         │                           │
      ├───────────────────────────►│  Chunk into 100-record    │
      │                            │  batches, execute in      │
      │                            │  parallel (concurrency=5) │
      │                            ├──────────────────────────►│
      │                            │◄──────────────────────────┤
      │  "847 updated. 0 errors."  │  Aggregate results        │
      │◄───────────────────────────┤                           │

Error Handling

Error	Cause	Solution
`520 CB_ILLEGAL_TOKEN: API token is invalid`	Token does not have permission for the target app or is malformed	Regenerate the API token in the app's settings. Ensure the token has the required permissions (view, add, edit, delete).
`409 CB_CONFLICT: Record revision mismatch`	Another user modified the record between your read and update	Fetch the latest revision with `kt records --app ID --id RECORD_ID` , review changes, then retry with the current revision number.
`400 CB_VA01: Missing required field`	A required field was not included in the create/update payload	Use `kt fields --app ID` to check required fields. Include all required fields in your `--data` payload.
`400 CB_VA01: Invalid field value`	Value does not match field type (e.g., text in a NUMBER field)	Verify the field type with `kt fields --app ID` . Ensure numbers are unquoted, dates use `YYYY-MM-DD` , and dropdown values match exactly.
`403 CB_NO02: No permission to proceed`	User or token lacks permission for the requested operation	Check app permissions in kintone admin. API tokens are scoped per-app; you may need a separate token.
`414 Request-URI Too Long`	Query string exceeds URL length limit (common with `in` operator)	Break large `in (...)` clauses into multiple queries. Use bulk endpoint for large ID lists.
`500 CB_IJ01: Internal server error`	kintone server issue, often during heavy load or complex calculations	Retry after 30 seconds. If persistent, check Cybozu status page. Simplify CALC field dependencies if triggered by specific records.

FAQ

1. What is the difference between API token and password authentication? API tokens are scoped to individual apps and are the recommended method. Password auth grants access to all apps the user can access but requires username/password storage. Use API tokens for production; password auth for ad-hoc admin tasks.

2. Can I access multiple apps with one command? Yes. Provide comma-separated API tokens in

KINTONE_API_TOKEN

for multi-app access, or use password auth for cross-app operations.

3. How does the query syntax work? kintone uses its own query language:

field_code operator "value"

. Example:

ステータス in ("商談中", "提案済") and 売上見込 > 1000000 order by 最終連絡 desc

4. What is the maximum number of records per bulk operation? 100 records per POST/PUT call, 500 IDs per DELETE call. The agent automatically chunks larger operations into batches.

5. Can I create new apps from the CLI? Yes. Use

kt apps --create --name "New App" --fields ./schema.json

to create an app with a predefined field schema. The agent handles preview and deployment.

6. How do I handle subtable (table) fields? Subtables are arrays of objects. In

--data

, provide them as:

{"テーブル": [{"value": {"品名": {"value": "Widget"}, "数量": {"value": "10"}}}]}

7. Does the agent support guest spaces? Yes. Set

KINTONE_GUEST_SPACE_ID

or use

--guest-space ID

per command. API endpoints are adjusted automatically.

8. Can I rollback a bulk update? kintone does not support native rollback. The agent creates a backup export before bulk operations (when

--backup

flag is used) so you can restore via

kt import

9. How do I handle file attachments? Upload:

kt records --app 1 --id 42 --upload-file ./doc.pdf --field 添付ファイル

. Download:

kt records --app 1 --id 42 --download-field 添付ファイル

10. What are kintone's API rate limits? kintone limits concurrent connections (typically 10 per domain) rather than requests-per-second. The agent manages connection pooling automatically.

11. Can I scaffold a kintone plugin project? Yes.

kt plugin init --name "My Plugin"

generates the full directory structure with

manifest.json

, config pages, and build scripts per Cybozu's specification.

12. How do I export data for BI tools? Use

kt export --app ID --format csv

for Tableau/Power BI, or

--format json

for custom pipelines. Add

--scheduled

for daily automated exports.

Data Storage

The kintone Agent maintains local state for efficient operations:

~/.kintone-agent/
├── config.yaml              # Domain, auth method, default app settings
├── cache/
│   ├── apps.json            # App list cache (TTL: 15 minutes)
│   ├── schemas/
│   │   ├── app_1.json       # Field schema cache per app (TTL: 1 hour)
│   │   └── app_5.json
│   └── query_history.json   # Recent queries for autocomplete
├── backups/
│   └── bulk_20260301_1.csv  # Pre-bulk-operation backup snapshots
├── logs/
│   ├── api-2026-03.log      # Monthly API log (tokens redacted)
│   └── bulk_operations.log  # Bulk operation audit trail
└── plugins/
    └── templates/           # Plugin scaffolding templates

Schema caches dramatically speed up validation and field resolution. Backups are created before destructive bulk operations and retained for 30 days. All authentication credentials are stored in the system keychain, never in plaintext files.

Comparison

Feature	kintone Agent	Airtable CLI	Notion CLI	Google Sheets CLI	Salesforce CLI
Japanese field names	Native UTF-8	Limited	Unicode	Unicode	Limited
No-code app builder	Full API	No	No	No	No
Workflow/process mgmt	Built-in	No	No	No	Apex required
Bulk operations	100/call native	10/call	Limited	Batch API	Bulk API 2.0
File attachments	Per-record	Per-record	Blocks	Drive link	Content
Subtables	Native	Linked records	Databases	No	Related lists
Plugin ecosystem	Cybozu marketplace	Extensions	Integrations	Add-ons	AppExchange
Guest space access	Native	Shared views	Shared pages	Shared sheets	Communities
On-premise option	Yes (cybozu.com)	No	No	No	Private Cloud
Query language	kintone QL	Formula	Filter API	Sheets formula	SOQL

Clawhub-skills kintone-agent

Overview

System Prompt Instructions

Environment Variables

Commands

`kt apps`

`kt records`

`kt create`

`kt update`

`kt search`

`kt bulk`

`kt fields`

`kt export`

`kt import`

`kt workflow`

Workflow

Error Handling

FAQ

Data Storage

Comparison