Port an existing Semgrep rule to other languages, one independent test-driven cycle per\nlanguage.
\nFor a new rule rather than a port, use semgrep-rule-creator — it takes a bug pattern\ndescription where this skill takes a finished rule. That skill is also the reference for\nrule-writing fundamentals: taint mode versus pattern matching, why tests come first, and\nhow to narrow a rule once it passes. Porting applies those same judgments in a new\nlanguage, so start there when the rule structure itself is the open question.
Porting is the same four phases repeated per language, so the orchestration ships as a\ndynamic workflow rather than as instructions to re-follow each run:
\n/semgrep-rule-variant-creator:port-rule-to-languages\nPass the three required arguments, and outputDir unless the working directory is where you\nwant the variants. One language per entry: \"Go and Java\" ports a single language named after\nthe phrase, and the script rejects it.
referencesDir has to be a resolved absolute path. Resolve it here, because no workflow script\ncan expand a variable. Try in order, first hit wins — the -d is the point, since a bare ls\nprints the names of the files inside the directory rather than the directory itself and leaves\nnothing to copy:
ls -d -- \"${CLAUDE_PLUGIN_ROOT}/skills/semgrep-rule-variant-creator/references\"${CODEX_PLUGIN_ROOT}, if that variable is set insteadfind ~/.claude ~/.codex . -type d -path '*/semgrep-rule-variant-creator/skills/*/references' -print -quit 2>/dev/nullThen confirm the directory that printed holds both reference files, with ls -1 -- \"<that path>\".
Pass the path exactly as printed. If all three come back empty, stop and say so rather than\nassembling a path by hand: the script rejects a relative path and an unexpanded token, but a\nhand-built absolute path that happens not to exist clears every guard it has, and the run then\nreports every language as passed having read no guidance at all.
\n{\n \"rulePath\": \"<path to the rule being ported>\",\n \"languages\": [\"Go\", \"Java\"],\n \"referencesDir\": \"<the absolute path the ls above printed>\",\n \"outputDir\": \"<where the variant directories should land>\"\n}\nA workflow script cannot expand {baseDir} or ${CLAUDE_PLUGIN_ROOT}, and has no filesystem\naccess to notice that it did not; an installed plugin does not sit in the user's project\neither, so referencesDir is the only route by which the references below reach the phase\nagents. The script rejects a run that omits it and one that passes a token instead of a path,\nrather than porting without them, since a port made without this guidance still reports every\nlanguage as passed. outputDir is the one optional argument, defaulting to the working\ndirectory, which is rarely what you want inside a repository.
It reads the rule once, then runs each language through the full cycle independently, and\nreports which languages passed, which failed validation, which it judged not applicable, which\nSemgrep cannot analyze at all, and which it stopped on — a language key it does not recognize,\ntwo entries resolving to one directory, or a refuter that never reported back. A stop names\nwhat to change and will happen again on a re-run, which is what separates it from an agent that\ndied. The rule travels as a path, not as text: every phase\nreads the file, because an agent asked to repeat a rule back verbatim does not — one\nHTML-escaped < and > and broke the <... ...> operator for every phase downstream.
If a run is interrupted while the session is still alive — you stopped it, or an agent hit a\nterminal error — relaunch it with\nWorkflow({scriptPath: \"…\", resumeFromRunId: \"<runId>\", args: {…}}), passing the same\narguments again. Arguments are not saved with a run, so a resume that omits them fails the\npre-flight check above before replaying anything; with them, languages that finished replay\nfrom cache and only the unfinished ones re-run.
Resume is same-session only, which rules it out for the interruption a long port is most\nlikely to hit: a session limit ends the session, and runs are stored under that session's own\ndirectory, so the next session cannot reach them. A run id it cannot resolve is not an error\neither — the workflow starts from scratch under that id and re-runs every language at full\ncost, with nothing saying so. Check the id is still there before counting on a resume:
\nls -d ~/.claude/projects/*/*/subagents/workflows/*/\nThat is where runs land today rather than a documented interface, so an empty result may mean the\nlayout moved rather than that the run is gone. The safe reading is the same either way: if you\ncannot confirm the id, or the session ended, re-invoke with the same arguments and point\noutputDir somewhere fresh. The script never deletes a directory, so a language that flipped to\nNOT_APPLICABLE on the second run leaves the first run's variant behind.
The script is workflows/port-rule-to-languages.js at the plugin root. It pins a\nreasoning effort per phase — cheap to read the rule, highest for translation and for the\nfix-until-green loop — and encodes the phase order, so a rule cannot be written before\nthe tests that specify it. It also keeps the two decisions that have no oracle out of any\nsingle agent's hands: a NOT_APPLICABLE verdict goes to an independent refuter before the\nlanguage is dropped, and failed validation is retried up to three times rather than\ntrusting one agent to iterate until green.
Run the phases by hand when you are porting to a single language and want to stay in the\nloop, or when a port is already half-finished and you only need one phase. The workflow is\nthe only delegation a port needs: one agent to read the rule, and four per language when\nthe port goes green first try — a refuted verdict adds one, and so does each validation\nretry. Nothing else here is large or independent enough to be worth its own agent, so\nrunning a phase by hand means doing it yourself rather than handing it to a subagent.
\nEach language runs all four before its variant is finished. A language that fails\nvalidation is unfinished; a language judged not applicable produces no directory.
\n1. Applicability analysis — decide whether the pattern belongs in the target language\nat all: does the vulnerability class exist there, does an equivalent construct exist for\neach source, sink, and sanitizer, and would the ported rule detect real risk rather than\na surface syntax match. Verdict is APPLICABLE, APPLICABLE_WITH_ADAPTATION, or\nNOT_APPLICABLE. NOT_APPLICABLE is the one verdict nothing downstream can contradict —\nit produces no tests, no rule, and no directory — so it earns a second opinion before you\nact on it. Answered separately, by running Semgrep: can Semgrep read this language at all?\nPerl has no frontend and Elixir's parser is Pro-only, and in both cases the bug class is\npresent while the rule is ungradeable — a different finding from NOT_APPLICABLE, which\nclaims the bug class is absent. See\napplicability-analysis.md\nfor worked examples of each verdict.
2. Test creation — write the test file first, in idiomatic target-language code. At\nleast two ruleid: cases and two ok: cases, each annotation on the line immediately\nabove the code it grades. Include the safe form that is the language's own idiom for\ndoing the thing correctly, since that is the false positive a port most often invents.
3. Rule translation — dump the AST for the target language and translate against what\nit shows, because pattern shape follows AST shape rather than source resemblance. Keep the\noriginal's detection intent and mode; change the id to <original-id>-<language>, the\nlanguages key, and add original-rule and ported-from metadata. See\nlanguage-syntax-guide.md.
4. Validation — semgrep --test is the acceptance criterion, and it must report that\nall tests passed. Missed lines mean the pattern is narrower than the vulnerability;\nincorrect lines mean it is broader. The test file is the specification, so fix the rule to\nsatisfy it. Stopping while tests still fail leaves the language unfinished, not done. See\nworkflow.md for reading a test failure and for\ntroubleshooting when a pattern will not match or taint will not propagate.
The acceptance criterion is one specific Semgrep: the version recorded when the rule was\nread. Switching binaries to get a green is the failure this guards against — an agent that\ncould not pass its Elixir tests installed the last OSS build shipping the Elixir parser and\nreported its genuine \"All tests passed\" for a port that is red here. Two other greens mean\nnothing: a rule Semgrep skipped still ends its run in \"All tests passed\", and so does a\ntest file whose extension Semgrep does not associate with the rule's language, since it\ngraded zero tests either way.
\nOne directory per applicable language, holding the ported rule and its test file:
\npython-command-injection-go/\n├── python-command-injection-go.yaml\n└── python-command-injection-go.go\nAll tests passed means the rule and its test file agree with each other; it is not\nevidence that the vulnerability class is exploitable in the target language, since the same\ncycle wrote both, so treat a finished variant as a candidate for review rather than a\nvalidated rule.
Port the rule you were handed to the languages you were asked for. Do not repair the\noriginal, widen it to catch a nearby bug class, or add a language nobody named; if the\noriginal looks wrong or an obvious target is missing, say so in one sentence and carry on\nwith the port as asked. Every language you were given gets finished — a port is done when\nits tests pass, not when its files exist.
\nKeep prose short and spend it on the result. Before the first tool call, say in one\nsentence what you are about to do. While a port runs, speak up when a verdict changes,\nwhen the target needs a pattern shape the original does not have, or when the tests will\nnot go green — not on every semgrep --test iteration. Then lead with the outcome: the\nfirst sentence says which languages passed, which failed validation, which were not\napplicable, and which Semgrep cannot analyze, with the detail after it. Correct an earlier statement when the error changes\nthe rule, the verdict, or what to do next, then keep going; a slip that changes nothing\nneeds no note.
Rule and test files are the size of the problem. A test file earns its length from\ndistinct constructs and distinct safe forms rather than from restatements of the same\ncase, and neither file needs comments repeating what the code already says.
\n| Rationalization | \nWhy It Fails | \nCorrect Approach | \n
|---|---|---|
| \"Pattern structure is identical\" | \nDifferent ASTs across languages | \nAlways dump AST for target language | \n
| \"Same vulnerability, same detection\" | \nData flow differs between languages | \nAnalyze target language idioms | \n
| \"Rule doesn't need tests since original worked\" | \nLanguage edge cases differ | \nWrite NEW test cases for target | \n
| \"Skip applicability - it obviously applies\" | \nSome patterns are language-specific | \nComplete applicability analysis first | \n
| \"I'll create all variants then test\" | \nErrors compound, hard to debug | \nFinish each language before the next | \n
| \"Library equivalent is close enough\" | \nSurface similarity hides differences | \nVerify API semantics match | \n
| \"Just translate the syntax 1:1\" | \nLanguages have different idioms | \nResearch target language patterns | \n
| \"Most tests pass\" | \nA partial rule reports partial truth | \nAll tests passed, or the port is unfinished | \n
| \"An older semgrep still parses this language\" | \nA green nobody can reproduce on the semgrep the rule must run under | \nReport the failing output and say the parser is Pro-only | \n
| \"The class exists there, so the rule ports\" | \nSemgrep has no Perl frontend and Elixir's is Pro-only; taint no-ops silently | \nConfirm semgrep can read the language before porting | \n
| \"Semgrep said all tests passed\" | \nIt says that over zero graded tests, for a rule it skipped or a file it never matched | \nCheck the rule ran and the test file's extension matches | \n
| Task | \nCommand | \n
|---|---|
| Run tests | \nsemgrep --test --config rule.yaml test-file | \n
| Validate YAML | \nsemgrep --validate --config rule.yaml | \n
| Dump AST | \nsemgrep --dump-ast -l <lang> <file> | \n
| Debug taint flow | \nsemgrep --dataflow-traces -f rule.yaml file | \n