Skills Authoring and Publishing Instructions

Use these rules when creating or editing canonical skill files and the associated discovery metadata under /static/.well-known/skills/.

This is the single internal source of truth for all Worldpay skill authoring and publishing work. Keep one authoring workflow, not separate public and private processes.

These instructions apply to:

• canonical skill markdown at /static/.well-known/skills/<slug>/SKILL.md
• per-skill metadata at /static/.well-known/skills/<slug>/index.json
• root discovery manifest at /static/.well-known/skills/index.json

Create implementation-first skill documents that coding agents can execute directly, and keep the public discovery metadata aligned with the canonical docs and product scope.

1. Create or update the canonical skill markdown at:

   • /static/.well-known/skills/<slug>/SKILL.md

2. Create or update the per-skill metadata file at:

   • /static/.well-known/skills/<slug>/index.json
   • It must include:
     • name
     • version
     • description
     • source reference (repositoryPath) to /static/.well-known/skills/<slug>/SKILL.md
     • public file reference to /.well-known/skills/<slug>/SKILL.md

3. Update the root discovery manifest at:

   • /static/.well-known/skills/index.json
   • Add or update a new entry in skills[] with:
     • unique name
     • human-readable title
     • concise description
     • homepage pointing to the product landing/docs route (for example /products/<product>/)
     • metadata pointing to /.well-known/skills/<slug>/index.json
     • files including /.well-known/skills/<slug>/SKILL.md

Keep this section order unless there is a strong reason to deviate:

1. # <Skill Name>
2. ## Purpose
3. ## When To Use This Skill
4. ## When Not To Use This Skill
5. ## Audience
6. ## Source Docs
7. ## Required Inputs Before Coding
8. ## Expected Outputs From The Assistant
9. ## Integration Decision Tree
10. ## Guardrails For Assistant Behavior
11. ## Core Reliability Rules
12. ## Minimal Request Pattern (when API-based)
13. ## Outcome Handling Contract
14. ## Testing Strategy
15. ## Security and Compliance Baseline
16. ## Go-Live Checklist
17. ## Editor Assistant Prompt Starters
18. ## Anti-Patterns

Every skill file must include frontmatter with these keys:

• name: lowercase slug matching the skill folder
• description: what the skill does and when to use it
• metadata: repo-specific string values for owner and last_updated (ISO date: YYYY-MM-DD)

Keep custom fields inside metadata, not at the top level. Quote last_updated so YAML parses it as a string.

• Write for engineers implementing production integrations.
• Prefer imperative instructions and deterministic behavior.
• Keep examples minimal but executable.
• Use full HTTPS URLs for published source docs in skill bodies so links work outside the documentation site; verify the published routes rather than linking to repository .md paths.
• Use relative paths for files bundled within the skill, and root-relative paths for public discovery metadata.
• Include explicit handling for unhappy paths.
• Avoid marketing language and product fluff.
• For API skills, always start with a required journey gate: exact flow, channel, and business pattern before coding.
• Prefer the canonical product journey names used in the docs (for example guest payment, stored card, recurring first, recurring subsequent, wallet, card-on-file).

Use this repeatable structure for all API-based skills:

1. Clearly define the exact product journeys covered.
2. Require the assistant to identify the flow before implementation begins.
3. State the canonical source docs for the primary journeys and stable feature guides.
4. Include a minimal request example that matches the documented request schema.
5. Add a decision tree for journey selection, 3DS or policy gates, and token/session vs direct data handling.
6. Include reliability, security, testing, and go-live requirements tailored to the API.
7. Exclude experimental or niche variants unless the product docs explicitly support them as standard.

• Do not invent API fields, endpoint behavior, or outcome semantics.
• If policy-dependent behavior exists (for example, review handling), require explicit business policy.
• Include at least one observability requirement (correlation IDs, logging, metrics, or tracing).
• Include at least one idempotency/retry requirement when API calls or events are involved.
• Include a test matrix covering happy path and high-risk/error paths.
• Keep metadata references limited to stable canonical product docs and feature guides; do not include experimental or unsupported variants in the public skill index.

• Keep canonical skill content, public .well-known files, and discovery metadata in sync.
• name/slug values must be consistent across the markdown file, metadata file, and root manifest.
• Public file paths must exist at the exact declared paths.
• Use lowercase slugs matching the folder name and metadata file name.
• Keep public discovery limited to stable, canonical docs and supported product journeys.
• Omit experimental or niche variants from the public metadata unless intentionally released.

If a change introduces a new published skill, also update references where relevant:

• /README.md published skills notes
• /products/ai/index.md summary text such as Currently published:
• /products/ai/index.md so the exact sentence reflects every skill currently listed in /static/.well-known/skills/index.json

• All changed .json files parse as valid JSON.
• Discovery metadata paths use root-relative URLs; source-doc links in skill bodies use verified HTTPS URLs.
• name/slug values are consistent across all three files.
• Public file exists at the exact path declared in both manifest files.
• Use the lowercase slug that matches the folder name and the metadata file name.
• Keep index references limited to stable, canonical docs; omit experimental paths from the public metadata unless intentionally released.
• Ensure the skill description, title, and journey scope match the actual product journeys and feature coverage.
• Confirm required frontmatter keys exist.
• Confirm required sections are present (or intentionally omitted with justification).
• Confirm the skill is journey-first and asks for the exact flow before implementation.
• Confirm all source-doc links reach published pages and match the intended product docs.
• Confirm the examples match the actual documented request schema, not a guessed or simplified shape.
• Confirm any included feature docs are stable and publicly supported.
• Update last_updated to the current date.

• Use concise headings and short bullet lists.
• Use fenced code blocks for request examples.
• Keep terminology consistent with the product docs.
• Preserve existing tone/style used by other skill files in this repository.

Before finishing changes to any /static/.well-known/skills/**/SKILL.md file:

• Confirm name, description, and metadata.owner / metadata.last_updated exist and the metadata values are strings.
• Confirm required sections are present (or intentionally omitted with justification).
• Confirm the skill is journey-first and asks for the exact flow before implementation.
• Confirm all source-doc links reach published pages and match the intended product docs.
• Confirm the examples match the actual documented request schema, not a guessed or simplified shape.
• Confirm any included feature docs are stable and publicly supported.
• Update last_updated to the current date.

Before finishing any skill change, also confirm:

• the metadata and root manifest match the published skill scope
• the public URL layout is root-relative and correct
• the skill is intentionally limited to stable, supported product journeys