sap-Codex-skills

SAP Codex Custom Skills — Templates and System Instructions

Custom skill templates and system instructions for SAP tasks (attribution: KEIDAI-TechTime/sap-Codex-skills). Grounded in this repo's template machinery: ABAP snippet catalog (template_repo.py), BAPI CSV template generation (xls_to_bapi.py), the karpathy behavioral wrapper, and the SKILL.md authoring pattern that makes the router activate the right skill.

1. Scope

2. Template Catalog (template_repo.py)

Catalog of ABAP snippets with {{PLACEHOLDER}} slots, keyed by module + action.

# Seed starter templates for all mapped actions (MM/SD/FI/PP/...)
npm run seed                        # = python scripts/template_repo.py seed

# List catalog: id, module, action, version, line count, placeholder count
python scripts/template_repo.py list

# Add your own template from an ABAP file
python scripts/template_repo.py add --file my_bapi_call.abap \
  --module MM --action CREATE_MATERIAL --title "Material create wrapper"

# Resolve placeholders into ready-to-paste ABAP
python scripts/template_repo.py resolve --template MM_CREATE_MATERIAL \
  --values '{"HEADER":"ls_head","RETURN_STRUCT":"ls_return"}'

# Export as JSON for abapGit / nugget packaging
python scripts/template_repo.py export --template CREATE_MATERIAL --format abapgit

--template accepts a template ID prefix, ACTION, or MODULE_ACTION. Ambiguous refs list candidates instead of guessing.

3. BAPI CSV Templates (xls_to_bapi.py)

Generate a CSV skeleton whose columns map to BAPI fields, fill it, then validate before conversion.

# Generate CSV template for module + action
npm run template -- --output mm_material.csv --module MM --action CREATE_MATERIAL
# = python scripts/xls_to_bapi.py template ...

# Validate a filled CSV against the BAPI field mapping
npm run csv:check -- --input mm_material.csv --module MM --action CREATE_MATERIAL

# Convert validated CSV to BAPI JSON payloads
npm run convert -- --input mm_material.csv --module MM --action CREATE_MATERIAL

4. System-Instruction Layer (karpathy wrapper)

karpathy-guidelines is the mandatory behavioral wrapper for every SAP operation. Its 4 principles:

1. Think — surface assumptions before coding: BAPI parameters, transport target (DEV/QA/PRD), required auth roles, basis release. If multiple BAPIs/paths exist, present options — never pick silently.
2. Simplify — minimum code that solves the problem: standard BAPI over custom FM, CDS view over ABAP report for reads, no speculative abstractions.
3. Surgical — touch only requested objects, match existing style/naming (ZCL_ prefix, casing), transport only changed objects, remove only orphans your own change created.
4. Goal-Verify — define verifiable success criteria ("MATNR returned, visible in MM03") and loop until they pass: syntax check, npm run abap:lint, unit tests, transport consistency.

Caveman compression is the output default: drop articles/filler/pleasantries, fragments OK, code blocks unchanged, pattern [thing] [action] [reason]. [next step]. Exception: security warnings and irreversible actions use full clarity.

5. Prompt Patterns for Router Dispatch

Phrase requests with module + action so the routing tree picks the right lane:

# Preview the route before executing
python scripts/sap_router.py route --action MM_CREATE_MATERIAL --module MM
python scripts/sap_router.py route --action SPRO_CONFIG

# Or via npm
npm run router -- --action MM_CREATE_MATERIAL
npm run router:gui -- --action SPRO_CONFIG      # Force GUI fallback

Vague prompts ("fix SAP thing") skip module/action matching and land in generic fallback — always name the module (MM/SD/FI/...) and a verb-object action.

6. Writing a Custom Skill Template

Skill activation is model-driven: Codex scans YAML frontmatter descriptions in .Codex/skills/*/SKILL.md. New skills MUST follow this pattern:

---
name: my-sap-skill                    # matches directory name exactly
description: One-line summary with the exact words users will type.
trigger:
  keywords: [6-10 lowercase phrases, tcodes, bapi names, module terms]
  intent: One sentence stating the user goal this skill serves
prerequisites:
  - Access/config the steps assume (auth, .env vars, transactions)
---

Body structure (max 200 lines): # Title, numbered ## sections with copyable commands, ## Pitfalls (Cause/Solution), ## Verification, ## Related.

System-instruction stacking order when a skill runs: karpathy wrapper (behavior) → caveman compression (output format) → your skill's instructions (domain steps). Skills add domain steps only — do not restate wrapper rules inside skill bodies.

After adding a skill, update ALL cross-file consistency targets: SKILL.md (master list), README.md (counts/diagrams), scripts/healthcheck.py (skill count threshold), AGENTS.md, package.json description.

Pitfalls

• resolve fails with KeyError → Cause: --values JSON missing a {{PLACEHOLDER}} used by the template. Solution: run template_repo.py list to see placeholder count, inspect template via export, supply every key.
• Seed appears to do nothing → Cause: seed skips (module, action) pairs already in the repo. Solution: expected idempotence; list to confirm, add a new version to override.
• CSV convert rejects file → Cause: columns do not match BAPI field mapping for module/action. Solution: regenerate skeleton with npm run template, run npm run csv:check before convert.
• New skill never activates → Cause: description lacks the words users actually type, or name differs from directory name. Solution: put exact trigger phrases (tcodes, BAPI names) in description + keywords; keep name = folder.
• Router picks wrong lane → Cause: prompt omitted module or used vague verbs. Solution: phrase as "MODULE verb object" (e.g. "SD create sales order batch"); preview with sap_router.py route.
• Healthcheck fails after adding a skill → Cause: healthcheck.py skill-count threshold no longer matches disk count. Solution: update threshold and the other cross-file consistency targets listed in section 6.

Verification

# Catalog seeded and listable
npm run seed
python scripts/template_repo.py list          # expect > 0 templates

# Template resolves to clean ABAP (no {{...}} left in output)
python scripts/template_repo.py resolve --template MM_CREATE_MATERIAL \
  --values '{"HEADER":"ls_h","DESCRIPTION":"ls_d","RETURN_STRUCT":"ls_r","MATERIAL_NUMBER":"lv_m","DESCRIPTION_TABLE":"lt_d"}'

# CSV template round-trip validates
npm run template -- --output /tmp/mm.csv --module MM --action CREATE_MATERIAL
npm run csv:check -- --input /tmp/mm.csv --module MM --action CREATE_MATERIAL

# New skill counted and healthy
npm run hc

Related

• karpathy-guidelines — the mandatory 4-principle wrapper summarized in section 4
• sap-router-skill — master dispatch table and routing decision tree
• run-sap-router-skill — smoke-testing template_repo.py / xls_to_bapi.py CLIs
• sap-bapi-integration — BAPI call patterns the seeded templates wrap
• caveman plugin — compression levels and cavecrew subagent delegation