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. Noodle refreshes an existing managed copy when it updates. 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 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.

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.

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

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, and 2 for a pre-run configuration failure.

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 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, but JSON output does, so agents must treat it as sensitive response data.

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.

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”