| name | vgs-collect-react-native-guide |
| description | Routes AI agents through VGS Collect React Native package work across integration, implementation, migration, troubleshooting, and code review. Use when guidance may depend on the installed @vgs/collect-react-native version. |
| metadata | {"internal":true,"author":"verygoodsecurity","version":"1.0.0"} |
VGS Collect React Native Guide
This is the single public skill entrypoint for the VGS Collect React Native package repository.
Use this skill when the task involves integrating, implementing, migrating, troubleshooting, or reviewing @vgs/collect-react-native usage in a customer React Native application.
When to Use
- First-time
@vgs/collect-react-native integration in a React Native app
- Feature implementation or refactor that touches collector setup, secure inputs, validation, submit flows, tokenization, alias creation, or card creation
- Migration between package versions or replacement of deprecated usage
- Troubleshooting package behavior, integration bugs, or version-specific regressions
- Code review of app code that uses
@vgs/collect-react-native
- Generating starter templates or guidance that depends on the installed package version
Bundled policy reference
This skill bundle must ship references/AGENTS.md.
When the skill is installed with npx skills add ..., load references/AGENTS.md first so the durable repository policy arrives with the skill itself.
References
| Topic | File |
|---|
| VGS Collect React Native package policy, security rules, flow selection, and versioned guidance | references/AGENTS.md |
AGENTS.md refresh logic
Treat references/AGENTS.md from this skill or the resolved VGS Collect React Native repository snapshot as the VGS Collect React Native policy file for this skill.
Do not confuse that VGS Collect React Native policy file with any customer-owned AGENTS.md that may exist in the user's app repository for unrelated project rules.
Before giving version-sensitive guidance:
- check whether the VGS Collect React Native
AGENTS.md policy file is present in the current skill or resolved repo context
- read the
**Package Version: x.y.z** header from that VGS Collect React Native AGENTS.md
- resolve the app's installed
@vgs/collect-react-native version
- confirm the VGS Collect React Native
AGENTS.md header version matches the app version, or matches the fallback docs snapshot being used
If the VGS Collect React Native AGENTS.md policy file is missing, download the correct references/AGENTS.md content from the canonical repository snapshot and use that updated file as the active rule set.
If the VGS Collect React Native AGENTS.md policy file exists but its Package Version header does not match the app version or resolved fallback snapshot, download and replace it with the correct references/AGENTS.md content from the canonical repository snapshot before continuing with version-sensitive guidance.
Core operating model
Use the active AGENTS.md snapshot as the base policy and decision framework.
Start with bundled references/AGENTS.md when the skill is being used standalone outside this repository.
Then decide whether that guidance is sufficient for the task.
If implementation details, version-specific API facts, migration steps, examples, or troubleshooting evidence are still needed, use the agent's normal retrieval tools to inspect the resolved repository snapshot, official docs, example app, source comments, release notes, and user-provided artifacts.
Search and retrieval may fill gaps, but they must not override AGENTS.md on:
- public-versus-private API boundaries
- root-package import requirements
- sensitive-data handling
- validation-before-submission requirements
- error-handling expectations
- task routing and flow-selection rules
Required workflow
- Load bundled
references/AGENTS.md immediately when the skill is being used standalone so the durable policy is available before any network or repo lookup.
- Resolve the installed
@vgs/collect-react-native package version before giving version-sensitive guidance.
- Read the
Package Version header from the currently available AGENTS.md, if one exists.
- Resolve the documentation snapshot for the app version.
- Reuse a previously loaded
AGENTS.md only when its Package Version header and docs source both match the resolved package version snapshot.
- If
AGENTS.md is missing or version-mismatched, download references/AGENTS.md from the resolved documentation source and update the active snapshot before continuing.
- Decide whether
AGENTS.md alone is sufficient for the task.
- If not, retrieve additional evidence from the resolved repository snapshot, official docs, example app, source comments, release notes, and user-provided artifacts.
- Apply the collection-flow rules from
AGENTS.md before generating guidance.
- Route the task into one primary mode:
integrate, implement, migrate, troubleshoot, or review.
- State which package version the guidance is based on.
Retrieval policy
Read the active AGENTS.md first for policy, constraints, invariants, allowed public APIs, and decision order.
For standalone skill installs, that means references/AGENTS.md first, then the resolved references/AGENTS.md snapshot once it has been matched to a versioned docs source.
Do not trust a bundled or cached AGENTS.md header blindly; compare its Package Version value against the resolved app version first, and refresh it from the repo when they differ.
Then classify whether more evidence is needed.
AGENTS.md alone is usually sufficient for:
- high-level architecture guidance
- security and compliance guardrails
- choosing between
submit, tokenize, createAliases, and createCard
- code review against known invariants
- generic starter templates that use documented public APIs
- deciding whether a requested approach conflicts with supported public behavior
Additional retrieval is required when the task depends on:
- exact API signatures or prop names
- version-specific behavior
- migration steps between versions
- examples for a specific React Native integration style
- troubleshooting tied to concrete errors, logs, or existing code
- release-specific caveats
- implementation hints available in repo docs, example code, or source comments
Preferred follow-up sources, in order:
- resolved-tag repository files such as
README.md, example app sources, and source comments
- official VGS docs for the React Native package
- release notes and tags
- user-provided code, logs, dependency manifests, lockfiles, and snippets
Source inspection may be used to confirm behavior, but must not justify use of private or undocumented APIs.
Snapshot reuse and invalidation
Agents should treat loaded repository guidance as a versioned docs snapshot.
A snapshot includes:
- repository identity
- git ref, tag, SHA, or default branch
- resolved package version status
- loaded
AGENTS.md
- optional release-note context
Reuse rule:
- Reuse a previously loaded
AGENTS.md only when the resolved package version, the Package Version header, and the docs source still match the active snapshot.
A stored snapshot may be reused for efficiency, but it is authoritative only when it matches the currently resolved package version and docs ref.
Invalidate and reload when:
- the resolved package version changes
- the docs ref changes from default branch to a tag, from one tag to another, or to a specific SHA
- the task is a migration and target-version docs are required
- previous version detection was inferred or unknown, and stronger evidence becomes available
- the active snapshot came from a fallback source and the canonical public repo snapshot later becomes available
Do not reuse an AGENTS.md snapshot across different package versions.
Do not continue using a default-branch AGENTS.md snapshot after an exact version tag has been resolved.
Do not continue using an AGENTS.md snapshot whose Package Version header differs from the resolved app version unless you have explicitly disclosed a nearest-compatible fallback.
Resolve version first
Determine whether @vgs/collect-react-native is already installed in the user's project.
Inspect evidence in this order when the runtime allows it:
- resolved dependency metadata such as
package-lock.json, yarn.lock, pnpm-lock.yaml, Bun lockfiles, or workspace lockfiles
- app dependency manifests such as
package.json
- installed package metadata such as
node_modules/@vgs/collect-react-native/package.json
- package-manager output such as
npm ls @vgs/collect-react-native, yarn why, or equivalent
- source imports or configuration references only when stronger evidence is unavailable
If the runtime does not allow project inspection, fall back in this order:
- user-provided dependency snippets
- user-stated package version
- user-provided build logs or package-manager output
- default-branch docs when version remains unknown
For each candidate, record:
- package name
- discovered version or version range
- evidence source file, snippet, or command
- confidence:
exact, constrained, inferred, or unknown
Treat the package as not installed only when no reliable evidence is found.
Do not block the task on version detection. If the version cannot be determined, continue using default-branch guidance and clearly label it as version-unverified.
Resolve the authoritative docs source
Canonical public docs source:
- Use
https://github.com/verygoodsecurity/vgs-collect-react-native as the canonical public repository for tags, release notes, and versioned copies of AGENTS.md and this skill.
- Do not treat private forks, private mirrors, or unrelated remotes as the public docs source of truth when they differ from the public repository.
- A local checkout may be used as the docs source only when it is the same repository content as the public
verygoodsecurity/vgs-collect-react-native snapshot needed for the task.
If an exact installed version is known:
- prefer the canonical public repository snapshot at the matching Git tag
- read
skills/vgs-collect-react-native-guide/references/AGENTS.md from that tag first
- read
skills/vgs-collect-react-native-guide/SKILL.md from that same tag when routing or wording consistency matters
- replace any missing or stale local
AGENTS.md with that tag-matched references/AGENTS.md copy before giving version-sensitive guidance
Map versions to tags like this:
- first try exact normalized matches such as
1.1.5 and v1.1.5
- if no exact tag exists and the version is semver-like, choose the nearest compatible tag with the same
major.minor and the highest patch that is not newer than the installed version
- if only a version range is known, choose the highest tag that satisfies the range
- if the dependency points to a git SHA or branch, prefer that exact repository revision when available
- if a local checkout remote disagrees with the public repository, the public repository wins for public skill guidance
- if the canonical public repo snapshot is not available locally, inspect the public remote tag snapshot before falling back
If the package is not installed:
- use the default-branch copies of
references/AGENTS.md and this skill
- in the public repository, the current default branch is
main
- if the local
AGENTS.md is missing or not already from the default-branch snapshot, refresh it from main
If version detection fails:
- use default-branch docs
- say explicitly that the installed version could not be determined
- refresh
AGENTS.md from the default branch if no local file exists or if the current header does not match the fallback snapshot you are using
If the public repository cannot be reached:
- use bundled
references/AGENTS.md and bundled SKILL.md as the authoritative fallback snapshot
- disclose that remote tag verification was not possible
If AGENTS.md, release notes, and resolved repository sources still do not provide enough detail for the task:
- consult
https://docs.verygoodsecurity.com for official product documentation
- prefer direct documentation pages that match the requested package feature or API behavior
- when you need documentation in markdown-friendly form, append
.md to the documentation page URL when supported
- treat
docs.verygoodsecurity.com as supplemental product documentation, not as a replacement for the versioned repository guidance above
React Native integration invariants
Treat the active AGENTS.md snapshot as the sole source of truth for integration invariants.
That includes:
- allowed public API surface and root-package import requirements
- private and undocumented API prohibitions
- sensitive-data handling and no-raw-value logging or persistence rules
- collector lifecycle, field registration, and component-driven integration expectations
- validation-before-
submit/tokenize/createAliases/createCard requirements
VGSError handling expectations
Do not restate, relax, or override those rules from examples, source inspection, release notes, or product docs. If another source appears to conflict, follow AGENTS.md and use additional retrieval only to fill in implementation detail.
Resolve collection flow before generating output
Apply the collection-flow rules from the active AGENTS.md snapshot before producing implementation, migration, troubleshooting, or review guidance.
Default to the smallest documented public API surface that satisfies the task.
Prefer component-driven integration in the customer's React Native app, not package-internal modifications.
Minimum missing-context questions
Ask a clarifying question only when the missing information materially changes the recommended API, migration path, or fix.
Useful missing-context questions include:
- installed
@vgs/collect-react-native version or dependency snippet
- whether the target flow is
submit, tokenize, createAliases, or createCard
- whether the task is first-time integration, an existing feature change, migration, troubleshooting, or review
- the relevant error message, log output, or code snippet for troubleshooting
- whether the user needs platform-specific React Native setup details for iOS, Android, or both
Do not ask for context that is not necessary for the current task.
Routing
Choose one primary mode.
integrate
Use when @vgs/collect-react-native is not yet installed in the downstream app, or when the task is specifically about first-time package adoption.
- confirm whether the package is already present
- determine the preferred supported installation method for the resolved package version based on the customer's project setup
- establish baseline collector setup and required prerequisites
- apply the collection-flow rules from
AGENTS.md before generating any submit or tokenization logic
- prefer the smallest documented public API surface
- include the tests or checks required by
AGENTS.md
implement
Use when adding or changing supported functionality in a downstream app with @vgs/collect-react-native.
- confirm prerequisites and supported installation path from
AGENTS.md
- apply the collection-flow rules from
AGENTS.md before generating code
- prefer the smallest documented public API surface
- implement the requested feature in the customer's app context, not just a generic snippet
- generate code and config with explicit validation and error handling
- include the tests or checks required by
AGENTS.md
- use placeholders only for secrets, identifiers, endpoints, and environment values that the user has not supplied
migrate
Use when moving between versions or replacing deprecated behavior.
- identify current version and target version
- load the current-version docs snapshot when available
- load the target-version docs snapshot
- use target-version
AGENTS.md as the authoritative destination rule set
- compare the existing code against the current-version docs when possible, and against the target-version docs for required changes
- use repository release notes to capture version-to-version changes and release-specific caveats
- replace deprecated or removed behavior with the newest documented public alternative
- call out any behavior changes that cannot be preserved exactly
troubleshoot
Use when the integration is failing or behaving unexpectedly.
- localize the failure before changing code
- prefer evidence from logs, tests, dependency state, or a minimal repro
- validate fixes against the resolved version's public behavior and invariants
- distinguish confirmed cause from likely cause and from workaround
review
Use when reviewing a patch, PR, or design.
- review against the resolved version's
AGENTS.md and public APIs
- retrieve additional implementation evidence when exact API details or version-specific behavior matter
- prioritize correctness, safety, compatibility, and missing tests
- flag private, deprecated, insecure, or version-incompatible behavior
- say explicitly when the reviewed code appears to target a different version
A task may have a secondary mode, but the primary mode controls planning and output.
Transparency requirements
Always state which package version guidance is based on.
When relevant, say one of:
Using @vgs/collect-react-native 1.1.5.Detected @vgs/collect-react-native 1.1.5 from package.json.Could not determine the installed @vgs/collect-react-native version; using latest guidance from the default branch.Exact tag 1.1.6 was not found; using nearest compatible tag 1.1.5.
Output contract
When this skill is used:
- begin by stating which package version was detected or assumed
- if the version could not be determined, say that latest default-branch guidance is being used
- then proceed using the active version-matched snapshot rather than stale assumptions
