Skip to content

Rewrite per-app skills based on the new App Use kit (v2.0) - #5

Open
andheroe wants to merge 2 commits into
membranedev:mainfrom
andheroe:rewrite-for-act-endpoint
Open

Rewrite per-app skills based on the new App Use kit (v2.0)#5
andheroe wants to merge 2 commits into
membranedev:mainfrom
andheroe:rewrite-for-act-endpoint

Conversation

@andheroe

@andheroe andheroe commented Apr 30, 2026 •
edited
Loading

Copy link
Copy Markdown

Mirror of membranehq/agent-skills#11 (already merged) applied across all per-app skills.

Why

This week several real users got stuck on the older action create → wait → run flow:

  • somerset12846 — action create returned an empty-shell action ID; every action run got "Action type undefined is not supported" (EXP-4952)
  • crra78xrt — action get 404'd on the just-created ID, agent gave up
  • xiaooh8888 — connection went into CLIENT_ACTION_REQUIRED; agent created a fresh connection instead of reconnecting and looped through connection patch
  • An openclaw eval account looped 45× on the same wrong-ID

The new /act endpoint accepts four dispatch styles — id, key, api, code — and the inline api / code paths require no pre-built action. Agents can go from "user asks → real response" in one round-trip with no BUILDING state to wait through.

That eliminates the entire failure mode for any agent that calls act --api for one-off requests. Saved actions become a power-user feature, not a prerequisite for the first call.

What changed in each per-app SKILL.md

Preserved per-app content:

  • Frontmatter (only version: "1.0" → "2.0")
  • H1, intro paragraph, "Official docs" link
  • ## <App> Overview resource hierarchy
  • ## Popular actions table
  • Connection URL extracted from the existing connection ensure line

Replaced universal content with the v2 act-based flow (mirrors integrate-anything v2):

  • New "Step 1 — Get a connection to " with Find→Reconnect→Create branching and the explicit "reconnect, don't replace" rule
  • New "Step 2 — Use the connection" with act --api / act --code / act --key / act --id dispatch table. act --api is recommended for the first call after a fresh connection — fastest path to a real response, no build/wait dance.
  • Connection state machine consolidated (READY / BUILDING / CLIENT_ACTION_REQUIRED / CONFIGURATION_ERROR / SETUP_FAILED)
  • clientAction.agentInstructions is the source of truth — explicit warning against shortcutting to "paste this URL"
  • New "Step 3 — Save reusable actions (optional)" — saved actions demoted from prerequisite to power-user feature
  • New "Error recovery" section: 401 (Membrane auth) vs disconnected external app vs failed action (with action-run-log get --details for diagnostics)
  • "Proxy requests" subsection dropped (folded into act --api)

Failure-mode coverage

Failure pattern observed during 04-28 to 04-30 Addressed by
action create wrong-ID bug (EXP-4952) act --api skips action create entirely
action get 404 after create act --api skips action get entirely
45-retry loop on a never-runnable action act --api + clearer state machine
Connection-patch loop on CLIENT_ACTION_REQUIRED "Reconnect existing, don't replace" rule

Scope

  • All 3,074 skills updated.
  • Generated by scripts/rewrite-app-skills.py — deterministic templating, idempotent.
  • Frontmatter `version: "1.0"` → `"2.0"` across all skills.
  • Branch was rebased onto current main with `-X theirs` to resolve conflicts cleanly (latest commits on main only touched skill content that this PR fully replaces).

After this merges

The same shape is already on agent-skills. Once this is merged, the ClawHub auto-sync (when working) should propagate the new content to the 91% of skills currently stale on ClawHub — addressing the discoverability/freshness problem we audited yesterday.

Test plan

  • Spot-check 3-5 representative skills (Salesforce, Slack, Linear, Google Workspace, an obscure one) against the new structure
  • Verify the act --api example reads as a useful first call for an agent
  • Confirm Popular actions tables render unchanged (only structural rewrite around them)
  • After merge, re-run the freshness audit (scripts/audit-skill-sync-content.py in insighter) to measure ClawHub sync recovery

🤖 Generated with Claude Code

@andheroe
andheroe force-pushed the rewrite-for-act-endpoint branch 3 times, most recently from a99b6e9 to 1d2230b Compare April 30, 2026 19:36
@andheroe andheroe changed the title Rewrite all per-app skills around the /act endpoint (v2.0) Rewrite per-app skills based on the new App Use kit (v2.0) Apr 30, 2026
gora050
gora050 requested changes May 1, 2026
View reviewed changes
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md
Comment thread skills/0codekit/SKILL.md
andheroe added a commit to andheroe/application-skills that referenced this pull request May 1, 2026
@andheroe @claude
Rewrite per-app skills based on the new App Use kit (v2.0)
7737d19 
Adopts the structure and contract defined in
membranehq/core:kits/app-use/kit.md across all 3,074 per-app skills.
Mirrors the integrate-anything v2 update at membranehq/agent-skills#11.

Major changes adopted from the kit:

- "Step 2 — Use the connection" introduces /act with four dispatch
  styles (--api, --code, --key, --id). Inline --api is recommended
  for the FIRST CALL after a fresh connection — no build step, no
  BUILDING state, no waiting. Saved actions become optional Step 3.

- Step 1 collapsed around `connection ensure` as the primary call (it
  covers find + create in one go). State-machine branching documents
  how to handle each returned state, including the explicit
  reconnect-existing rule for CLIENT_ACTION_REQUIRED — never create a
  fresh connection to replace a disconnected one.

- `clientAction.agentInstructions` is the source of truth. Explicit
  warning against shortcutting to "paste this URL" when
  agentInstructions are present.

- New "Error recovery" section distinguishes 401 (Membrane auth) from
  disconnected external-app from failed action, with
  `action-run-log get --details` for diagnostics.

- Standalone "Proxy requests" section dropped — proxy semantics are
  now folded into `act --api`.

- A "Running an action from the table above" snippet is added directly
  after the Popular actions table so the table isn't an orphan list:
  shows `act --key <key> --connectionKey <slug> --input '<json>'`.

Targeted at activation failures observed during 04-28 to 04-30:
- somerset12846's `action create` returning empty-shell action ID
- crra78xrt's action-get 404 after create
- A bot account's 45-retry loop on a never-runnable action
- xiaooh8888's connection-patch loop on CLIENT_ACTION_REQUIRED

Per-app content preserved unchanged: frontmatter, app intro, official
docs link, "## <App> Overview" resource hierarchy, "## Popular actions"
table, connection URL.

Frontmatter version bumped 1.0 → 2.0 across all skills.

Generated by scripts/rewrite-app-skills.py in the insighter repo.
Addresses review feedback on PR membranedev#5 from gora050:
  - Restored "either browser OR print URL" auth wording
    (interactive mode often unavailable in agentic runtimes)
  - Dropped "and base-URL routing" phrasing (security review concern)
  - Collapsed Step 1 around `connection ensure` (find+create in one)
  - Added explicit `act --key` example after the popular actions table

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@andheroe
andheroe force-pushed the rewrite-for-act-endpoint branch from 1d2230b to 7737d19 Compare May 1, 2026 13:23
@andheroe @claude
Rewrite per-app skills based on the new App Use kit (v2.0)
844a3b8 
Adopts the structure and contract defined in
membranehq/core:kits/app-use/kit.md across all 3,074 per-app skills.
Mirrors the integrate-anything v2 update at membranehq/agent-skills#11.

Major changes adopted from the kit:

- "Step 2 — Use the connection" introduces /act with four dispatch
  styles (--api, --code, --key, --id). Inline --api is recommended
  for the FIRST CALL after a fresh connection — no build step, no
  BUILDING state, no waiting. Saved actions become optional Step 3.

- Step 1 collapsed around `connection ensure` as the primary call (it
  covers find + create in one go). State-machine branching documents
  how to handle each returned state, including the explicit
  reconnect-existing rule for CLIENT_ACTION_REQUIRED — never create a
  fresh connection to replace a disconnected one.

- `clientAction.agentInstructions` is the source of truth. Explicit
  warning against shortcutting to "paste this URL" when
  agentInstructions are present.

- New "Error recovery" section distinguishes 401 (Membrane auth) from
  disconnected external-app from failed action, with
  `action-run-log get --details` for diagnostics.

- Standalone "Proxy requests" section dropped — proxy semantics are
  now folded into `act --api`.

- A "Running an action from the table above" snippet is added directly
  after the Popular actions table so the table isn't an orphan list:
  shows `act --key <key> --connectionKey <slug> --input '<json>'`.

Targeted at activation failures observed during 04-28 to 04-30:
- somerset12846's `action create` returning empty-shell action ID
- crra78xrt's action-get 404 after create
- A bot account's 45-retry loop on a never-runnable action
- xiaooh8888's connection-patch loop on CLIENT_ACTION_REQUIRED

Per-app content preserved unchanged: frontmatter, app intro, official
docs link, "## <App> Overview" resource hierarchy, "## Popular actions"
table, connection URL.

Frontmatter version bumped 1.0 → 2.0 across all skills.

Generated by scripts/rewrite-app-skills.py in the insighter repo.
Addresses review feedback on PR membranedev#5 from gora050:
  - Restored "either browser OR print URL" auth wording
    (interactive mode often unavailable in agentic runtimes)
  - Dropped "and base-URL routing" phrasing (security review concern)
  - Collapsed Step 1 around `connection ensure` (find+create in one)
  - Added explicit `act --key` example after the popular actions table

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@andheroe
andheroe force-pushed the rewrite-for-act-endpoint branch from 7737d19 to 844a3b8 Compare May 1, 2026 13:25
@andheroe

andheroe commented May 1, 2026

Copy link
Copy Markdown
Author

All four review comments addressed in 844a3b8:

  1. Auth section — restored 'either browser OR print authorization URL' wording.
  2. 'and base-URL routing' phrase — removed.
  3. Step 1 — collapsed around connection ensure (covers find + create).
  4. Popular actions table — added act --key example immediately below it.

Ready for re-review.

@andheroe
andheroe requested a review from gora050 May 1, 2026 13:27
gora050
gora050 requested changes May 4, 2026
View reviewed changes
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md Outdated
Comment thread skills/0codekit/SKILL.md Outdated
@andheroe @claude
Address review feedback: drop superfluous content from skill template
ac6a91e 
- Remove getmembrane.com link from intro (not needed in description).
- Remove --tenant explainer paragraph (referenced --workspaceKey /
  --tenantKey, which are not introduced anywhere else in the skill).
- Drop "or the Popular actions table below" hint from act --api — the
  Popular actions are saved Membrane actions, not raw API specs.
- Remove the inline `act --code` section and the --code dispatch row.
  The agent does logic itself; surfacing remote-code-execution in
  per-app skills also raises a security-review concern.
- Remove the duplicate "Running an action from the table above"
  subsection — already covered by step 2 (Reusable action by key).
- Renumber: 2a (api), 2b (key), 2c (discover); was 2a/2b/2c/2d.

Generated by scripts/rewrite-app-skills.py.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@andheroe

andheroe commented May 4, 2026

Copy link
Copy Markdown
Author

All 6 review comments addressed in ac6a91e (template change, regenerated all 3,074 skills):

  1. Dropped getmembrane.com link from intro.
  2. Dropped --tenant explainer paragraph.
  3. Dropped Popular-actions-table reference from act --api.
  4. Dropped act --code section + dispatch row entirely (security + use-case feedback).
  5. (same as 4)
  6. Dropped duplicate "Running an action from the table above".

Sections renumbered 2a/2b/2c. Ready for re-review.

@andheroe
andheroe requested a review from gora050 May 4, 2026 15:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gora050 gora050 Awaiting requested review from gora050

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@andheroe @gora050