AI agent skills

AI agent skills are reusable instruction sets that extend what your coding agent can do. The noodle-use skill teaches agents to work with noodle collections through supported automation commands and, when needed, .yml and .env files directly.

1Human prompt

“Create a users API collection with shared auth and a development environment.”

2Agent + noodle-use

noodle-usesupported automation first

CLIcollection create

FILESusers/*.yml + .env

CHECKcollection audit

3Versioned collection

users-api/├── settings.yml├── users/list.yml└── .environments/development.env

plain files, ready for Git

4Noodle TUI

noodledevelopment

USERSGET list

GET /users

Safety boundary Secrets stay in the OS vault. Browser authorization stays human.

The noodle-use skill turns a prompt into a reviewable collection: it prefers supported non-interactive commands, edits YAML or dotenv files when needed, audits the result, and leaves the collection ready to open in Noodle. Secret values and browser authorization remain outside agent-authored files.

Installation

Install the skill globally for your agent:

noodle agent install

The built-in installer writes a managed copy to ~/.agents/skills/noodle-use and links detected Claude, Cursor, Codex, and OpenCode installations to it. Standalone updates refresh an existing managed copy. After a Homebrew upgrade, run noodle agent install again to refresh it. Use --json for scripted installation.

If any detected path contains an unmanaged copy, Noodle preserves every copy and reports all conflicts before changing anything. Review those paths, then run noodle agent install --force only when you intentionally want Noodle to replace all of them. Forced installation keeps backups until every target has been installed and rolls completed replacements back if a later target fails.

For other clients, use the skills CLI fallback:

npx skills add wilfredinni/noodle --skill noodle-use -g

The fallback supports GitHub Copilot and 70+ other agents.

What agents can do

Once the skill is installed, ask your agent to:

Create

Scaffold collections, add requests with JSON or XML bodies (including :name URL path parameters), declare sandboxed inline or external pre/post scripts, response captures, assertions, and suite tags, set up folders with inherited tags, auth, and headers, create environments, and register the collection path in ~/.config/noodle/config.yml so it appears in noodle’s workspace switcher.

Organize

Rename, restructure, deduplicate headers across requests, flatten deep nesting, and reorder folders while preserving auth inheritance chains. Moving or renaming changes a request ID, so agents should explain that its generated timeline data (including large-body sidecars) will be orphaned rather than silently claiming to preserve it.

Configure

Set collection names, descriptions, response-history retention, cookie policy, credential-free proxy policy, and TLS/mTLS metadata in settings.yml. Agents can use --noproxy when one run must bypass proxy settings and --insecure only when the user intentionally disables TLS verification for that invocation.

Declare secure environment values with blank # @secret placeholders and use noodle secret set, list, and delete for OS-vault values. Agents should never place proxy credentials, mTLS passphrases, or environment secrets in YAML, command arguments, or logs.

Environment keys must match ^\w+$, with _color reserved for metadata, and values preserve everything after the first =. Request variables use $NAME; write $$NAME when the request must contain the literal text $NAME.

Agents must not assume the OS vault is available on headless Linux. If a secret operation reports that Secret Service or the login keyring collection is unavailable, direct the user to the Linux and headless environment setup. For unattended jobs, use the same-named process environment variable or an external secret manager instead of trying to unlock a graphical keyring prompt.

Agents can inspect storage health with noodle cookie list and clear or recover a jar with noodle cookie clear. Cookie list output includes live cookie values, so agents should redact it from logs and shared reports. Per-request sendCookies: false disables outgoing jar cookies but still captures response cookies. Cookie locks with valid metadata for a confirmed exited owner recover automatically while preserving session data and an abandoned-lock backup. Live or uncertain owners remain locked; agents should investigate contention before considering a reset.

Agents can configure server NTLMv2, AWS SigV4, OAuth 1.0a, or OAuth 2.0 auth through request or folder YAML when the user provides the needed values. They should declare NTLM passwords, AWS secret keys and session tokens, OAuth consumer and token secrets, client secrets, passwords, and private signing keys as secrets. SigV4 and OAuth 1 body hashes do not support multipart bodies. OAuth 2 can use discovery_url for an OIDC issuer, or discovery_url_kind: document for an exact metadata URL. OpenAPI supports openIdConnect; Postman requires explicit endpoints for the selected grant.

Agents must not place OAuth 2 tokens, authorization codes, PKCE verifiers, or generated state in collection files. First-time authorization code and implicit flows require the human user to complete browser authorization in the TUI. Automation may reuse or refresh stored credentials, but it never opens a browser. Generated client-code snippets are unavailable for NTLMv2, AWS SigV4, OAuth 1.0a, and OAuth 2.0 requests.

Run and verify

The skill also documents the interactive Runner: humans can inspect completed responses, Results, and Console during a run, stop with s or Stop, and leave with Escape before resuming the current workspace with F5. Execution-affecting edits remain locked through cleanup. Each collection keeps its latest settled run in memory across reloads and collection switches until app exit, including the executed configuration and selected iteration/result. In settled details, o opens the request or selected result’s source, with a searchable picker for multiple test origins. Retained body previews and diagnostics have explicit truncation or omission notices; no disk history is added. See the Runner guide.

Run one request with noodle request run, selected request IDs or folder paths with noodle collection run <dir> [<target>...], or omit targets to run the entire collection. Folder targets end in / and include nested requests; overlapping targets run once in collection order.

Agents can run dynamic suites with repeated --tag filters, remove matching requests with repeated --exclude-tag filters, and stop after the first failed request with --fail-fast. Every include tag must match; any exclude tag removes a request. Request tags combine with every ancestor folder’s tags, and exclusion wins when both filter types match. Structured output keeps executed requests in data.results, fail-fast skips in data.skipped, and aggregate counts plus fixed failure categories in data.summary. Collection runs exit 0 on success, 1 after a completed request failure, 2 for a pre-run configuration failure, and 130 for SIGINT/SIGTERM cancellation. Interrupted rows carry cancelled: true; unstarted selections use skip reason cancelled. Summary completed, cancelled, and unstarted keep partial results accountable. See cancellation results.

Agents can add --delay <milliseconds> to wait between selected requests. The value must be a non-negative safe integer; no delay runs after the last request or after fail-fast stops the run.

Agents should keep credentials in declared secret variables so Noodle can apply its redirect protections. Noodle rejects HTTPS-to-HTTP redirects. When the origin changes, it disables request auth, removes sensitive headers and headers containing known secrets, and refuses to preserve a body containing a known secret. Redirects that discard the body may continue. A configured request timeout appears as a transport failure, while caller-triggered cancellation returns the partial collection result without counting the interrupted row as a request failure.

Agents can author synchronous or async scripts.pre and scripts.post inline in YAML or through collection-relative ./file.js references using the frozen noodle namespace. Pre prepares a request; post reads the completed response after captures and before assertions, with optional URL-scoped cookie operations. Pre failure skips HTTP; post failure preserves the response/captures and still runs later post blocks, assertions, and tests. Both phases support seeded English test data, noodle.time helpers for timestamps, timezones, and elapsed durations, and explicit environment/secret persistence through noodle.run.set/unset. Manual sends and request run honor persistence; collection runs and the Runner report transient suppression.

Pre/post scripts can await saved requests with noodle.runRequest or literal HTTP calls with noodle.sendRequest. Agents can add read-only tests with test, expect, JSON Schema draft-07, and the supported matchers. Collection settings.yml and nested folder.yml files can share scripts and tests across descendants. See Scripted Tests and the Script API for ordering, limits, and rollback.

The installed skill includes generated noodle-script.d.ts declarations for external JavaScript editor assistance. A triple-slash reference path comment can point to that file; phase-specific NoodleScript.Pre, Post, and Tests interfaces support tooling while runtime checks remain authoritative. Humans can edit the same scripts in TUI editors. Agents should continue using files and the non-interactive CLI.

For generated payloads, use $random and $time body placeholders with JSON-literal arguments. Agents can use typed standalone JSON placeholders or escaped quoted text, with one substitution pass before pre scripts. See body templates.

For repeated inputs, use collection run --data <file> with CSV or JSON. Each row gets fresh variables and a transient copy of the initial cookie jar; noodle.iteration exposes the original row to scripts and tests. The Runner guide documents validation, path resolution, and iteration results.

Treat scripted collections as trusted code: noodle.env.get can read secrets and place them in the outgoing request. Prefer declarative fields, captures, and assertions when sufficient. See Scripting for the API migration, lifecycle, results, and storage restrictions.

Agents can download original bytes with noodle request run <id> --collection <dir> --output <file> --json. Choose an authorized new destination and remember that downloads are unredacted. Binary JSON results contain metadata only; body captures/assertions cannot parse them as JSON. Binary timeline and Runner details retain no downloadable body.

Agents can add declarative response assertions for status, timing, case-insensitive headers, and JSON body paths. Failed HTTP responses or assertions make run commands exit nonzero. Human output does not print raw actual assertion values. JSON output redacts known secrets from expected and actual values, but can still contain sensitive server data. Both request run and collection run exit 2 for pre-run configuration failures and 1 for completed request failures.

Agents can also add object-form capture mappings with required value, optional enabled: false, and optional persist: secret|environment. Captures override same-named environment values in RunScope, and the latest successful capture wins. A failed capture leaves any earlier value unchanged, fails the command, and does not stop the remaining collection requests. Persistence is available only to manual TUI sends and CLI request run; collection runs always stay transient. Agents should add persistence only when the user explicitly wants the active or selected environment changed, and must treat secret capture results as fully redacted.

Evaluate

Audit collections for:

• Security: hardcoded tokens, undeclared secure values, HTTP vs HTTPS, tokens in URLs, missing auth, unsafe TLS overrides, and credential-bearing proxy URLs
• REST practices: correct HTTP methods, URL patterns, Content-Type headers
• Structure: orphan requests, folder naming, nesting depth
• Environment hygiene: declared but unused vars, missing vars across environments

Import

Import OpenAPI 3.0, Swagger 2.0, Postman, and Insomnia v4/v5 JSON exports with noodle import. For a format Noodle does not support, agents should map only directly supported behavior to Noodle files and report unsupported scripts, tests, and auth flows. Supported imports preserve XML bodies from OpenAPI, Swagger, Postman, and Insomnia sources. Postman dynamic, dotted, and hyphenated placeholders are rejected before Noodle writes an import. Noodle supports inline and external scripts and tests at request, folder, and collection level. Postman and Insomnia imports preserve compatible source already using supported Noodle APIs or conservative JavaScript built-ins, without translating provider APIs. Imports retaining scripts or tests require a new collection. Ordered warnings identify omitted hooks with item and phase details, unsupported global names, and compatibility or placement reasons, without exposing omitted source or literal values. Review those warnings before running the collection.

The bundled skill includes a generated scripting API reference with every member, phase capability, and fixed runtime limit, alongside noodle-script.d.ts for external editors. When bundled references do not resolve a troubleshooting question, agents can consult the online documentation index and check noodle --version before applying guidance for a newer release.

Export

Export a Noodle collection as OpenAPI 3.0.3 or a Postman Collection v2.1 bundle with noodle export. Agents should use a path outside the collection and warn before sharing request literals, which may include secrets. @/ upload paths expand to absolute home-directory paths in Postman bundles, so agents should also warn about local-path disclosure. XML bodies export as literal OpenAPI examples and raw Postman XML.

Example prompts

• “Scaffold a noodle collection for the Stripe API with auth and a few endpoints”
• “Audit my collection for security issues and REST best practices”
• “Import this Insomnia export to a noodle collection”
• “Export this collection as a Postman bundle”
• “How many requests are in the Stripe API collection?”
• “What’s the average response time for the login request on my Stripe collection?”
• “Change the expand layout keybinding to Alt+I”
• “Set Catppuccin as my theme”
• “Set this collection’s proxy to inherit global settings and retain 10 responses per request”
• “Disable automatic cookie handling for this collection”
• “Order the folders on the Stripe collection from Z to A”
• “Set up basic auth on the Posts folder for $basic_user and $basic_password”
• “Configure OAuth 2 authorization code with S256 PKCE for this request”
• “Add a pre-request script that signs this JSON body with a secret HMAC key”