# Evaluation Report

Evaluation of the `doca-argp` skill before publication through Skill Evaluator.

This benchmark summarizes 3-Tier Evaluation from Skill Evaluator results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.

## Evaluation Summary

- Skill: `doca-argp`
- Evaluation date: 2026-07-23
- Skill Evaluator profile: `external`
- Environment: `k8s-sandbox`
- Dataset: 4 evaluation tasks
- Attempts per task: 1
- Pass threshold: 50%
- Overall verdict: PASS

## Agents Used

- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`)
- Codex (`openai/openai/gpt-5.5`)

## Metrics Used

Reported benchmark dimensions:

- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.

Underlying evaluation signals used in this run:

- `security` (Security): checks for unsafe operations, secret leakage, and unauthorized access.
- `skill_execution` (Skill Execution): verifies that the agent loaded the expected skill and workflow.
- `skill_efficiency` (Efficiency): checks routing quality, decoy avoidance, and redundant tool usage.
- `accuracy` (Accuracy): grades final-answer correctness against the reference answer.
- `goal_accuracy` (Goal Accuracy): checks whether the overall user task completed successfully.
- `behavior_check` (Behavior Check): verifies expected behavior steps, including safety expectations.

## Test Tasks

The benchmark dataset contained 4 evaluation tasks:

- Positive tasks: 3 tasks where the skill was expected to activate.
- Negative tasks: 1 tasks where no skill was expected.
- Unlabeled tasks: 0 tasks where positive/negative intent could not be inferred.

Task composition is derived from the evaluation dataset when possible. Entries with `expected_skill` set are treated as positive skill-activation cases, while entries with `expected_skill: null` are treated as negative activation cases.

## Results

| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 4 | 100% (+0%) | 100% (+0%) |
| Correctness | 4 | 100% (+25%) | 100% (+25%) |
| Discoverability | 4 | 98% (+36%) | 95% (+33%) |
| Effectiveness | 4 | 100% (+37%) | 100% (+24%) |
| Efficiency | 4 | 99% (+52%) | 100% (+73%) |

Score values show skill-assisted performance. Values in parentheses show uplift versus the no-skill baseline when baseline data is available.

## Tier 1: Static Validation Summary

Tier 1 validation passed with observations. Skill Evaluator ran 1 checks and found 7 total findings.

Top findings:

- MEDIUM SCHEMA/folder_hierarchy: Unexpected nesting depth for general skill (`skills/libs/doca-argp`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/libs/doca-argp/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/libs/doca-argp/SKILL.md`)
- MEDIUM SCHEMA/author_missing: Author not specified in metadata (`skills/libs/doca-argp/SKILL.md`)
- LOW SCHEMA/unexpected_file: Unexpected 'CAPABILITIES.md' in skill root (`skills/libs/doca-argp/CAPABILITIES.md`)

## Tier 2: Deduplication Summary

This tier was not run or did not produce findings in this report.

## Publication Recommendation

The skill is suitable to proceed toward Skill Evaluator publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

# DOCA Arg Parser capabilities, version overlay, errors, observability, safety

**Where to start:** Pick the H2 anchor that matches your question
(param model / parameter types / standard CLI surface / JSON
config / version / errors / safety) and read that section
end-to-end. The tables in each section are the load-bearing
content; the prose around them is interpretation.

Read this file when the loader sent you here from
[SKILL.md](SKILL.md). For the *how* of executing each pattern
(the verbs `configure / build / modify / run / test / debug`),
jump to [TASKS.md](TASKS.md). For the canonical DOCA
version-handling rules that this skill layers an Arg-Parser
overlay on top of, see
[`doca-version`](../../doca-version/SKILL.md).

## Pattern overview

Every Arg Parser question this skill teaches resolves into one
of FIVE patterns. The patterns are CLASSES — they apply across
every DOCA release and every sample, not just the worked
examples shown.

| Pattern | When it applies (class shape) | Where the substance lives |
| --- | --- | --- |
| 1. Reuse, do not rewrite | The user is modifying a shipped DOCA sample's CLI (adding / removing / renaming a flag) and is tempted to swap the Arg Parser for `getopt` / `argparse` / hand-rolled parsing | [`## Capabilities and modes`](#capabilities-and-modes) reuse rule + [TASKS.md ## modify](TASKS.md#modify) |
| 2. Register before start | New params are registered against the Arg Parser instance BEFORE `doca_argp_start` parses argv; registering after parse is the most common first-app failure | [`## Capabilities and modes`](#capabilities-and-modes) lifecycle table + [TASKS.md ## configure](TASKS.md#configure) |
| 3. Pick the parameter type | Choose from the six-value public enum (string, int, boolean, device, device representor, double); JSON config is a separate input surface, not a type | [`## Capabilities and modes`](#capabilities-and-modes) parameter-type table + [TASKS.md ## modify](TASKS.md#modify) |
| 4. Inherit the standard CLI surface | Keep `--device`, `--representor`, `--rep-list`, `--json` (`-j`), `--sdk-log-level` working the same way they do in the sibling samples; users learn one CLI for all of DOCA | [`## Capabilities and modes`](#capabilities-and-modes) standard-surface table + [TASKS.md ## modify](TASKS.md#modify) |
| 5. Diagnose an Arg Parser error | Map symptom (`BAD_STATE`, `INVALID_VALUE`, `NOT_SUPPORTED`, `IO_FAILED`) to root cause without leaving the Arg Parser layer prematurely | [`## Error taxonomy`](#error-taxonomy) + [TASKS.md ## debug](TASKS.md#debug) |

Two cross-cutting rules that apply to *every* pattern above:

- **The shipped sample's `*_main.c` is the canonical reference,
  every time.** doca-argp does not ship its own dedicated
  sample tree; instead, every DOCA sample's `*_main.c` (under
  `/opt/mellanox/doca/samples/<library>/<sample>/`) is a
  working, version-matched Arg Parser usage. Quote the
  installed file, not a remembered API shape.
- **The standard CLI surface is the user's mental model,
  not a stylistic preference.** When a user invokes any DOCA
  sample, they expect `--device`, `--representor` (or
  `--rep-list`), `--json` (`-j`), and `--sdk-log-level` to
  behave the same way as in the sibling samples. Adding a flag
  on top of that surface is fine; replacing the surface breaks
  the cross-sample mental model and is a regression.

## Capabilities and modes

DOCA Arg Parser is a **small, foundational CPU-side library**.
It has no hardware accelerator behind it, no DOCA Core context,
and no progress engine — it owns *parsing*, not *execution*. On
top of that small surface, it layers a param-registration
lifecycle, a small parameter-type set, the shared DOCA standard
flag surface, and the JSON-config file integration.

**The Arg Parser lifecycle.** Every consumer follows the same
register-before-start order. The agent must not invent steps;
the public surface is closed.

| Step | Call | What it does | Order constraint |
| --- | --- | --- | --- |
| Init | `doca_argp_init(<program-name>, <user-config>)` | Creates the per-process Arg Parser instance; allocates the default standard-flag set | Must be the FIRST `doca_argp_*` call in the program |
| Register | `doca_argp_param_create` → `doca_argp_param_set_*` (short name, long name, value-callback, description, type) → `doca_argp_register_param` | Adds one `doca_argp_param` to the instance for each app-specific flag | Must happen AFTER `doca_argp_init` and BEFORE `doca_argp_start`; registration after start returns `BAD_STATE` |
| Start (parse) | `doca_argp_start(argc, argv)` | Walks argv (and any `--json <path>` / `-j <path>` file), calls each matching param's value-callback with the parsed value, fails fast on the first invalid value | Runs ONCE per process; a second `_start` returns `BAD_STATE` |
| Destroy | `doca_argp_destroy()` | Frees the per-process instance and every registered `doca_argp_param` | Should pair with `_init` on every exit path, including error paths |

**Parameter types.** The full public `enum doca_argp_type` the Arg
Parser exposes. Picking the right one is what makes argv
validation and JSON-config validation Just Work. The enum has
**six** real values (`DOCA_ARGP_TYPE_STRING`,
`DOCA_ARGP_TYPE_INT`, `DOCA_ARGP_TYPE_BOOLEAN`,
`DOCA_ARGP_TYPE_DEVICE`, `DOCA_ARGP_TYPE_DEVICE_REP`,
`DOCA_ARGP_TYPE_DOUBLE`) — do not silently omit the latter three.

| Type (enum) | Argv shape | JSON shape | Typical use |
| --- | --- | --- | --- |
| `DOCA_ARGP_TYPE_STRING` | `--my-flag VALUE` | `"my-flag": "VALUE"` | File paths, free-form strings |
| `DOCA_ARGP_TYPE_INT` | `--my-flag 1234` | `"my-flag": 1234` | Queue depth, message size cap, max-num-tasks |
| `DOCA_ARGP_TYPE_BOOLEAN` | `--my-flag` (presence sets true) | `"my-flag": true` | Enable a code path that is off by default |
| `DOCA_ARGP_TYPE_DEVICE` | `--my-flag <PCI>` | `"my-flag": "<PCI>"` | A PCIe-address-bearing flag whose value the Arg Parser opens as a `doca_dev` for you (e.g. `--device 0000:03:00.0`) — preferred over hand-rolling the device open via `DOCA_ARGP_TYPE_STRING` |
| `DOCA_ARGP_TYPE_DEVICE_REP` | `--my-flag <rep>` | `"my-flag": "<rep>"` | A representor-name-bearing flag whose value the Arg Parser opens as a `doca_dev_rep` for you (e.g. `--representor pf0vf0`) — DPU-side counterpart to `_TYPE_DEVICE` |
| `DOCA_ARGP_TYPE_DOUBLE` | `--my-flag 12.5` | `"my-flag": 12.5` | Floating-point knobs (e.g. timeouts in seconds, fractional caps) |
| JSON config file *(special, not a type)* | `--json /path/to/file.json` (or `-j`) | n/a (this IS the JSON file) | Drive any of the above from a file instead of expanding argv. The real flag is `--json` / `-j`, NOT `--json-config` — do not invent the longer name. |

**The standard DOCA CLI surface.** Every shipped sample already
registers these (via `doca_argp_init` and a small set of
default params) so the user learns ONE CLI for all of DOCA.
Modifications must preserve this surface.

| Flag | Value type | Meaning |
| --- | --- | --- |
| `--device <PCI>` | String (PCIe address, e.g. `0000:03:00.0`) | Which `doca_dev` the program opens |
| `--representor <name>` | String (representor name, e.g. `pf0vf0`) | Which `doca_dev_rep` the DPU side opens (Comch and similar libraries) |
| `--rep-list` | Bool flag | Print the visible representors and exit (DPU-side discovery) |
| `--json <path>` / `-j <path>` | String (path to a JSON file) | Read parameter values from a JSON file instead of expanding argv. The flag is registered as `--json` (`-j`) by `doca_argp.cpp::register_param` (the internal static helper; the public entry point is `doca_argp_register_param`); the bundle previously called this `--json-config`, which is not the real flag. |
| `--sdk-log-level <level>` | String (one of the DOCA Log level names) | Set the SDK-side DOCA Log threshold for this run |

**JSON-config integration.** The `--json <path>` flag (also
short-form `-j <path>`; the long name is `--json`, NOT
`--json-config`) is not optional cosmetic detail — shipped
samples with non-trivial configurations expect operators to
drive them from a file (the command line becomes unreadable
past ~5 flags). The JSON keys match the registered long names;
the JSON value types match the registered parameter types; an
unknown JSON key fails with `DOCA_ERROR_NOT_SUPPORTED` (pedantic parsing) per
[`## Error taxonomy`](#error-taxonomy).

**Path selection — when doca-argp is the right answer.** This
is a small library, but its scope is sharp. Walk this rule
before recommending the Arg Parser path.

| Use doca-argp when … | Do not use doca-argp when … |
| --- | --- |
| Modifying a shipped DOCA sample's CLI (add / remove / rename a flag) — reusing the Arg Parser keeps the sample's CLI consistent with every sibling sample | The program never calls a `doca_*` symbol — there is no DOCA-side interaction to begin with, so a language-native CLI parser is the right answer (and avoids dragging in `libdoca-argp` for no benefit) |
| Building a new DOCA-using app that wants operators to learn the standard `--device` / `--representor` / `--json` (`-j`) / `--sdk-log-level` CLI conventions instead of inventing a fresh one | The user genuinely needs a POSIX getopt feature the Arg Parser does not cover (e.g. optional-argument optional-value forms) — and is willing to accept the cost of breaking sample-CLI consistency for that specific need; even then, prefer layering doca-argp + the extra parser, not replacing it |
| Driving a complex configuration from a JSON file (`--json <path>` / `-j <path>`) — the file format and key validation come for free | The CLI surface is interactive (REPL, prompt loop) — that is not what an arg parser is for; reach for a TUI / REPL library instead |

## Version compatibility

For the canonical DOCA version-detection chain, the four-way
match rule, NGC container semantics, and the
headers-win-over-docs rule, see
[`doca-version`](../../doca-version/SKILL.md). The body lives
there; this skill does not duplicate it.

**The Arg-Parser-specific overlay** is:

- **Presence is the first check; version is the second.**
  doca-argp is a small, foundational library — agents tend to
  assume it is always present. It is not always installed in
  every package profile. Use `pkg-config --exists doca-argp`
  for the presence check FIRST, then `pkg-config --modversion
  doca-argp` for the version. Per the cross-cutting rule in
  [`doca-version CAPABILITIES.md ## Observability`](../../doca-version/CAPABILITIES.md#observability),
  the build-time `pkg-config` value is the authority for *"is
  this library available for me to link against?"*.
- **`doca-argp.pc` and `doca-common.pc` must both match
  `doca_caps --version`** at the four-way-match check (per
  [`doca-version CAPABILITIES.md ## Version compatibility`](../../doca-version/CAPABILITIES.md#version-compatibility)).
  A common partial-install pattern after a DOCA upgrade is
  that `doca-argp.pc` lingers from the previous release; route
  to [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug)
  layer 2 before any Arg-Parser-layer diagnosis.
- **Headers in $(pkg-config --variable=includedir doca-common)
  win over public docs.** Per the headers-win-over-docs rule
  in [`doca-version`](../../doca-version/SKILL.md), if a
  public Arg Parser doc page mentions a `doca_argp_*` symbol
  that is not in the installed `doca_argp.h`, the headers
  describe what *this* install can call; the docs describe
  what *some* release shipped. The agent must quote the
  headers, not the docs URL, when the two disagree.

## Error taxonomy

Arg-Parser-specific overlays on the cross-library
`DOCA_ERROR_*` taxonomy. The cross-library taxonomy itself
lives in
[`doca-programming-guide CAPABILITIES.md ## Error taxonomy`](../../doca-programming-guide/CAPABILITIES.md#error-taxonomy);
the rows below are the *Arg Parser surface* meaning that the
agent must disambiguate before falling back to the
cross-library response.

| Error | Arg Parser context where it shows up | Arg-Parser-specific cause |
| --- | --- | --- |
| `DOCA_ERROR_BAD_STATE` | `doca_argp_register_param` after `doca_argp_start`; a second `doca_argp_start` in the same process; any `doca_argp_*` call after `doca_argp_destroy` | Lifecycle violation. Walk the lifecycle table in [`## Capabilities and modes`](#capabilities-and-modes); the most common case is the program registering an extra param inside the value-callback of another param (i.e. during `_start`, not before). |
| `DOCA_ERROR_INVALID_VALUE` | `doca_argp_start` when an argv value (or JSON-config value) does not match the registered param's declared type | Type mismatch. Re-check the registered type vs. the value the user is passing (e.g. param declared as `int` but operator wrote `--my-flag 0x40`). The fix is on the declaration side OR the operator side, not a retry. |
| `DOCA_ERROR_NOT_SUPPORTED` | `doca_argp_start` when a JSON-config key is not the long name of any registered param (pedantic parsing rejects the unknown field — see `doca_argp.cpp::json_keys_validation`) | The JSON file references a flag the program never registered. Either the key is a typo, or the program is older than the JSON config it is being fed. Diff the registered long names against the JSON keys. |
| `DOCA_ERROR_IO_FAILED` | `doca_argp_start` when `--json <path>` (or `-j <path>`) points at a file the process cannot open or read | File-system failure (missing path, wrong permission, JSON syntax error). Resolve at the OS layer (`ls -l <path>`; `cat <path> \| jq .`) before any code change. |
| `DOCA_ERROR_NOT_SUPPORTED` (operator-side) | `doca_argp_start` against argv containing an unknown long / short name (an unsupported program flag, per the `doca_argp_start` doc in `doca_argp.h`) | The operator passed a flag the program never registered. The fix is on the operator side; the program may surface its own `--help` listing all registered params via the per-param descriptions. |

The agent's rule: **never recommend a retry loop on a
`doca_argp_*` `DOCA_ERROR_*`**. Every row above is an
authoring or operator mistake, not a transient state — the fix
is to correct the call site, the registration, the JSON key, or
the file path, not to retry.

## Observability

The Arg Parser's observability surface is small but
load-bearing: the program's own `--help` output (synthesized
from the registered param descriptions) is what the operator
reads, and DOCA Log is what the program emits at parse time.

Three primary signals the agent should reach for:

1. **The `--help` output.** Every Arg Parser instance
   auto-generates a `--help` listing from `doca_argp_init`'s
   default standard flags plus every registered param's
   description. The agent should ask the user to run
   `./<binary> --help` before any other debug step — *if the
   new flag is not listed, registration never happened*; *if
   the standard flags are not listed, `doca_argp_init` was
   skipped*.
2. **The parsed-value callback fires.** Each registered
   `doca_argp_param`'s value-callback runs once per matched
   flag (argv or JSON-config). A param that registers cleanly
   but whose callback never fires means the operator never
   passed the flag — *not* that the library dropped it. Add a
   one-line log inside the callback before assuming a parser
   bug.
3. **DOCA Log lines from the Arg Parser layer.** Per the
   cross-cutting observability primitives
   (`DOCA_LOG_LEVEL=trace`, `--sdk-log-level`, the trace build
   flavor) in
   [`doca-debug CAPABILITIES.md ## Observability`](../../doca-debug/CAPABILITIES.md#observability),
   the Arg Parser routes its own messages through DOCA Log; a
   trace-level run shows the per-param parse calls and the
   JSON-config file read.

For the install-tree observability (logger names, package
layout) defer to
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).

## Safety policy

> **Overlay on the bundle-wide hardware-safety meta-policy.** The rules below are this skill's per-artifact overlay on the cross-cutting rules in [`doca-hardware-safety` CAPABILITIES.md ## Safety policy](../../doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically [### Per-artifact overlay pattern](../../doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

The Arg Parser's safety surface is **lower-stakes than most DOCA
libraries** for string, integer, boolean, and double parameters: that
parsing runs in the user's process and holds no kernel-side resources.
`DOCA_ARGP_TYPE_DEVICE` and `DOCA_ARGP_TYPE_DEVICE_REP` are different:
the parser opens the selected `doca_dev` or `doca_dev_rep` handle and
can fail on device visibility or permissions. Opening a handle is not
itself a hardware-state mutation, but the agent must identify the
target and surface those access failures. If the callback or
downstream workflow uses that handle for a state change, load
`doca-hardware-safety` and apply its stricter gate before that change.

The load-bearing safety rule is structural, not access-control
shaped: **when modifying a shipped DOCA sample's CLI, reuse the
Arg Parser; do not replace it with `getopt` / `argparse` /
hand-rolled parsing**. The reasons this is a safety rule, not
a stylistic preference:

- **Cross-sample CLI consistency is a user contract.**
  Operators of DOCA samples carry mental models across
  libraries (`--device`, `--representor`, `--json` / `-j`,
  `--sdk-log-level` behave the same in every sample). A
  modified sample that silently breaks that contract becomes a
  trap for operators and a debugging time-sink that looks like
  a library bug.
- **`--json <path>` (`-j <path>`) is shared infrastructure** (the
  long name is `--json`, NOT `--json-config`). Sample
  CI, sample documentation, and operator runbooks all assume
  the JSON-config path works. A hand-rolled parser drops the
  JSON path silently; `--help` still looks right; the failure
  surface is *"my JSON file is ignored"*, which the operator
  has no obvious place to file against.
- **Lifecycle violations are caught only when doca-argp owns
  parsing.** The `BAD_STATE` / `INVALID_VALUE` / `NOT_SUPPORTED` /
  `IO_FAILED` ladder in
  [`## Error taxonomy`](#error-taxonomy) only fires when the
  program goes through `doca_argp_*` — a hand-rolled parser
  re-creates this ladder by accident, badly.

The narrow exception (path-selection rule in
[`## Capabilities and modes`](#capabilities-and-modes)): when
the program never calls a `doca_*` symbol at all, doca-argp is
not the right tool — a language-native parser is — and pulling
in `libdoca-argp` adds a build-time dependency for no agent or
user benefit. The agent must distinguish *"DOCA-using app
modifying its CLI"* (reuse mandatory) from *"non-DOCA CLI
tool"* (language-native parser is correct).

## Deferred topic boundaries

This skill scopes itself to the DOCA Arg Parser library.
Adjacent topics the agent will get asked but should route
elsewhere:

- **Generic CLI-parser feature requests** (variadic flags,
  subcommand routing, shell-completion generation) — outside
  this skill. The Arg Parser exposes a deliberately small
  public surface; route the user to a language-native parser
  layered on top if a feature is genuinely required.
- **DOCA Core context, progress engine, and `doca_mmap`
  internals** — owned by
  [`doca-programming-guide`](../../doca-programming-guide/SKILL.md).
  Arg Parser is upstream of the Core context (it parses the
  CLI that selects which device the Core context will open);
  it does not redefine the Core context.
- **DOCA Log internals** (registry names, per-source level
  filters) — owned by the public DOCA Log guide reachable
  through
  [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).
  Arg Parser registers `--sdk-log-level` as a default flag but
  does not own the log layer it configures.
- **Cross-cutting `DOCA_ERROR_*` taxonomy** — owned by
  [`doca-programming-guide CAPABILITIES.md ## Error taxonomy`](../../doca-programming-guide/CAPABILITIES.md#error-taxonomy).
  This skill adds the Arg Parser overlay, not the taxonomy
  itself.
- **Cross-cutting debug ladder** (install / version / build /
  link / runtime / program / driver) — owned by
  [`doca-debug ## debug`](../../doca-debug/TASKS.md#debug).
  This skill's `## debug` overlays the program layer.

## Description: <br>
Use this skill for hands-on DOCA Arg Parser CLI work on a shipped sample or new DOCA-using app — adding, removing, or renaming flags; wiring the doca_argp lifecycle; picking parameter types from the full public enum; preserving the standard DOCA CLI surface; or debugging DOCA_ERROR codes from doca_argp calls. <br>

This skill is ready for commercial/non-commercial use. <br>

## Owner
NVIDIA <br>

### License/Terms of Use: <br>
Apache 2.0 AND CC-BY-4.0 <br>
## Use Case: <br>
Developers and engineers building or modifying DOCA-using applications who need to add, remove, or configure CLI flags using the DOCA Arg Parser library, wire the argp lifecycle, or debug argp-related errors. <br>

### Deployment Geography for Use: <br>
Global <br>

## Requirements / Dependencies: <br>
**Requires API Key or External Credential:** [No] <br>
**Credential Type(s):** [None] <br>

Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate. <br>

## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>

## Reference(s): <br>
- [DOCA Arg Parser Documentation](https://docs.nvidia.com/doca/sdk/DOCA-Arg-Parser/index.html) <br>
- [DOCA Samples](https://github.com/NVIDIA-DOCA/doca-samples) <br>


## Skill Output: <br>
**Output Type(s):** [Code, Shell commands, Configuration instructions, Analysis] <br>
**Output Format:** [Markdown with inline C code blocks and bash commands] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>

## Evaluation Agents Used: <br>
- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) <br>
- Codex (`openai/openai/gpt-5.5`) <br>



## Evaluation Tasks: <br>
Evaluated against 4 evaluation tasks (3 positive skill-activation, 1 negative) in the k8s-sandbox environment with 1 attempt per task and a 50% pass threshold. <br>

## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>

Underlying evaluation signals used in this run: <br>
- `security`: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
- `skill_execution`: Verifies that the agent loaded the expected skill and workflow. <br>
- `skill_efficiency`: Checks routing quality, decoy avoidance, and redundant tool usage. <br>
- `accuracy`: Grades final-answer correctness against the reference answer. <br>
- `goal_accuracy`: Checks whether the overall user task completed successfully. <br>
- `behavior_check`: Verifies expected behavior steps, including safety expectations. <br>



## Evaluation Results: <br>
| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 4 | 100% (+0%) | 100% (+0%) |
| Correctness | 4 | 100% (+25%) | 100% (+25%) |
| Discoverability | 4 | 98% (+36%) | 95% (+33%) |
| Effectiveness | 4 | 100% (+37%) | 100% (+24%) |
| Efficiency | 4 | 99% (+52%) | 100% (+73%) |

## Skill Version(s): <br>
d53d861 (source: git SHA, committed 2026-07-23) <br>

## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

---
license: Apache-2.0
name: doca-argp
description: >
  Use this skill for hands-on DOCA Arg Parser CLI work on a
  shipped sample or new DOCA-using app — adding / removing /
  renaming flags; wiring `doca_argp_init` → register params →
  `doca_argp_start` → `doca_argp_destroy` in order; picking a
  parameter type from the full public enum
  (`DOCA_ARGP_TYPE_STRING`, `_INT`, `_BOOLEAN`, `_DEVICE`,
  `_DEVICE_REP`, `_DOUBLE` — six values, not three);
  preserving the standard `--device` / `--representor` /
  `--json` (`-j`; real flag is `--json`, NOT `--json-config`) /
  `--sdk-log-level` surface; or debugging
  `DOCA_ERROR_BAD_STATE` / `INVALID_VALUE` / `NOT_SUPPORTED` /
  `IO_FAILED` from `doca_argp_*`. Trigger on implicit
  phrasings: "add a custom flag to a DOCA sample", "should I
  use getopt here", "BAD_STATE registering a new param", "my
  JSON config key is rejected", or "my sample's --json is
  ignored". Refuse and route elsewhere for variadic-flag /
  subcommand / shell-completion features, DOCA Core context,
  or DOCA Log internals.
metadata:
  kind: library
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux
  (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or
  ConnectX NIC attached. Reads the user's local install via
  `pkg-config doca-argp` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
---

# DOCA Arg Parser

**Where to start:** This skill assumes DOCA is already installed
and the user is doing **hands-on CLI work** on a DOCA sample or
new DOCA-using app. Open [`TASKS.md`](TASKS.md) if the user wants
to *do* something (configure / build / modify / run / test /
debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the
question is *what can the Arg Parser express* on this version. If
the user has not installed DOCA yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first. If the user is
about to rewrite a sample's CLI with `getopt` / `argparse` /
custom parsing instead of reusing the Arg Parser, read the
load-bearing rule in
[`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
before any code change.

## Example questions this skill answers well

The CLASSES of Arg Parser questions this skill is built to
answer, each with one worked example. The agent should treat the
*class* as the load-bearing piece — the worked example is a
single instance.

- **"How do I add a new flag to a DOCA sample without breaking
  the standard CLI?"** — worked example: *"add `--my-flag` to
  `/opt/mellanox/doca/samples/doca_dma/dma_local_copy/` so the
  sample still accepts `--device <PCI>` and `--sdk-log-level
  <level>` the same way it did before"*. Answered by the
  reuse-the-Arg-Parser rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the register-before-start workflow in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"Why does `doca_argp_param_set_*` return `BAD_STATE` on my
  second call?"** — worked example: *"registering a new param
  after `doca_argp_start` has already parsed argv"*. Answered by
  the lifecycle order in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the error-taxonomy row in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  for `DOCA_ERROR_BAD_STATE`.
- **"Can I drive a sample from a JSON file instead of a long
  command line?"** — worked example: *"point a sample at
  `./my-config.json` so the operator does not have to type out
  ten flags every time"*. Answered by the `--json <path>`
  integration in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the JSON-config-file workflow in
  [`TASKS.md ## modify`](TASKS.md#modify) and
  [`TASKS.md ## run`](TASKS.md#run).
- **"My `--my-flag X` value is rejected as `INVALID_VALUE` — why?"** —
  worked example: *"declared the param as `int` but passed
  `--my-flag 0x40`"*. Answered by the parameter-type table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the type-mismatch row in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
- **"Is `doca-argp` even on my installed DOCA?"** — worked
  example: *"a colleague's sample mentions doca-argp but I want
  to confirm before I depend on it"*. Answered by the presence
  + version-detection rule in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
  which cross-links the canonical detection chain in
  [`doca-version`](../../doca-version/SKILL.md).
- **"Should I use doca-argp here, or is this case actually
  outside its scope?"** — worked example: *"writing a host-side
  CLI tool that never calls a `doca_*` symbol"*. Answered by the
  path-selection rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  *Use doca-argp when … / Do not use doca-argp when …* bullets.

## Audience

This skill serves **external developers building or modifying
DOCA-using applications** — i.e., users whose code already calls
`doca_*` (directly in C/C++, or through FFI/bindings from
another language) and who need the standard DOCA CLI surface so
operators of the resulting binary do not have to relearn how to
invoke each sample. It is *not* for NVIDIA developers
contributing to the Arg Parser library itself.

**Language scope.** DOCA Arg Parser ships as a C library with
`pkg-config` module name `doca-argp`. The shipped samples are
written in C. C and C++ consumers are the canonical case; the
worked examples in `TASKS.md` assume that path. Other-language
consumers (Rust, Go, Python, …) consume the same `*.so` through
FFI or language-specific bindings; the skill's contribution in
that case is to keep the lifecycle, parameter-type, JSON-config,
standard-flag-surface, and error-taxonomy guidance
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.

## When to load this skill

Load this skill when the user is doing hands-on DOCA Arg Parser
work, in any language. Concretely:

- Adding, removing, or renaming a CLI flag on a shipped DOCA
  sample or on a new app that wants to share the standard DOCA
  CLI surface (`--device <PCI>`, `--representor <name>`,
  `--rep-list`, `--json <path>`, `--sdk-log-level
  <level>`).
- Wiring `doca_argp_init` / `doca_argp_start` /
  `doca_argp_destroy` into a `main()`, including the
  register-before-start lifecycle and the cleanup-on-exit
  contract.
- Registering a `doca_argp_param` (short name, long name, value
  callback, description for `--help`) with a parameter type
  drawn from the six-value public enum: string, int, boolean,
  device, device representor, or double. A JSON config file is an
  input surface for those parameters, not a parameter type.
- Reading complex configurations from a JSON file via the shared
  `--json <path>` flag instead of expanding the command
  line.
- Confirming the build- and runtime-side Arg Parser version on
  the user's install (`pkg-config --exists doca-argp`,
  `pkg-config --modversion doca-argp`) before depending on it.
- Debugging a `DOCA_ERROR_*` returned from a `doca_argp_*` call
  (lifecycle vs. type-mismatch vs. unknown JSON key vs.
  unreadable file).
- Designing or extending non-C bindings (Rust, Go, Python, …)
  that wrap the Arg Parser C ABI — for the lifecycle,
  parameter-type, JSON-config, and standard-flag rules the
  wrapper must honor.

Do **not** load this skill for general DOCA orientation, install
of DOCA itself, or non-Arg-Parser library questions. For those,
use
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).

## What this skill provides

This is a **thin loader**. The body keeps only the orientation
needed to pick the right next file. The substantive
Arg-Parser-specific material lives in two companion files:

- `CAPABILITIES.md` — what the Arg Parser can express on this
  version: the param-registration model, the small set of
  public parameter types, the standard DOCA CLI surface every
  sample shares, the `--json <path>` file integration,
  the register-before-start lifecycle, the Arg Parser error
  taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set),
  the observability surface (the `--help` output and the
  DOCA Log channel), and the safety / path-selection policy
  (when reusing doca-argp is mandatory; when a language-native
  parser is the right answer).
- `TASKS.md` — step-by-step workflows for the six in-scope Arg
  Parser verbs: `configure`, `build`, `modify`, `run`, `test`,
  `debug`. Plus a `Deferred task verbs` block that points
  out-of-scope questions at the right next skill.

The skill assumes a host or BlueField where DOCA is already
installed at the standard location. It does not cover installing
DOCA — that path goes through
[`doca-setup`](../../doca-setup/SKILL.md).

## What this skill deliberately does not ship

This skill is **agent guidance**, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:

- **Pre-written DOCA Arg Parser usage code, in any language.**
  The verified Arg Parser usage is the `*_main.c` file in every
  shipped DOCA sample at
  `/opt/mellanox/doca/samples/<library>/<sample>/`. The agent's
  job is to route the user to that file and prescribe a
  minimum-diff modification on it via the universal
  modify-a-sample workflow in
  [`doca-programming-guide`](../../doca-programming-guide/SKILL.md),
  layered with the Arg-Parser-specific overrides in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **Standalone build manifests** (`meson.build`,
  `CMakeLists.txt`, `Cargo.toml`, …) parked inside the skill.
  The agent constructs the build manifest *in the user's
  project directory* against the user's installed DOCA, where
  `pkg-config --modversion doca-argp` is the source of truth.
- **A `samples/`, `bindings/`, or `reference/` subtree** of any
  kind. A mock or incomplete artifact in this skill's tree,
  even one labeled "reference", is misleading: users will read
  it as buildable.

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is
   in scope.
2. **For the param-registration model, parameter types, the
   standard DOCA CLI surface, the `--json <path>` rule,
   the register-before-start lifecycle, error taxonomy,
   observability, and the path-selection / safety policy, see
   [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug — see [TASKS.md](TASKS.md).**

Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules, and
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "Arg-Parser-specific
guidance".

## Related skills

- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) —
  the routing table for every public DOCA documentation source
  and the on-disk layout of an installed DOCA package. The Arg
  Parser URL is
  `https://docs.nvidia.com/doca/sdk/DOCA-Arg-Parser/index.html`;
  the canonical on-disk usage example is any sample's
  `*_main.c` under `/opt/mellanox/doca/samples/`.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation,
  install verification, and the *I have no install yet* path
  with the public NGC DOCA container. This skill assumes its
  preconditions are satisfied.
- [`doca-version`](../../doca-version/SKILL.md) — canonical
  DOCA version-handling rules. This skill's `## Version
  compatibility` cross-links the four-way match rule and adds
  the Arg-Parser-specific presence-check overlay.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) —
  the bundle's structured-tools precedence rule (detect / prefer
  / fall back / report). The Command appendix in
  [TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) —
  general DOCA programming patterns shared by every library:
  the canonical `pkg-config` + meson build pattern, the
  universal modify-a-shipped-sample first-app workflow, the
  universal lifecycle, the cross-library `DOCA_ERROR_*`
  taxonomy, and the program-side debug order. This skill layers
  Arg-Parser specifics on top.
- [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting
  debug ladder (install / version / build / link / runtime /
  program / driver). Arg-Parser-specific debug (lifecycle
  violations, type-mismatch on a registered param, unknown JSON
  key) overlays on top of that ladder.

# SKILLCARD.yaml — provisional, signed at NVCARPS scan time
# Schema: https://github.com/NVIDIA/skills/blob/main/docs/skill-cards.mdx
# This file is generated by `runner/build_skillcards.py`; do not hand-edit.
# Re-run after any change to SKILL.md frontmatter or the deep-E2E baseline.

schema_version: "1"

identity:
  name: "doca-argp"
  artifact_id: "doca-argp"
  kind: "library"
  version: "TBD-at-sign-time"          # NVCARPS fills from the source ref
  signature: "TBD-at-sign-time"        # NVCARPS-generated SHA + ed25519 sig
  signed_by: "TBD-at-sign-time"        # NVCARPS identity (NVIDIA-PSIRT signing key)

description: "Use this skill for hands-on DOCA Arg Parser CLI work on a\nshipped sample or new DOCA-using app — adding / removing /\nrenaming flags; wiring `doca_argp_init` → register params →\n`doca_argp_start` → `doca_argp_destroy` in order; picking a\nparameter type from the full public enum\n(`DOCA_ARGP_TYPE_STRING`, `_INT`, `_BOOLEAN`, `_DEVICE`,\n`_DEVICE_REP`, `_DOUBLE` — six values, not three);\npreserving the standard `--device` / `--representor` /\n`--json` (`-j`; real flag is `--json`, NOT `--json-config`) /\n`--sdk-log-level` surface; or debugging\n`DOCA_ERROR_BAD_STATE` / `INVALID_VALUE` / `NOT_SUPPORTED` /\n`NOT_FOUND` / `IO_FAILED` from `doca_argp_*`. Trigger on implicit\nphrasings: \"add a custom flag to a DOCA sample\", \"should I\nuse getopt here\", \"BAD_STATE registering a new param\", \"my\nJSON config key is rejected\", or \"my sample's --json is\nignored\". Refuse and route elsewhere for variadic-flag /\nsubcommand / shell-completion features, DOCA Core context,\nor DOCA Log internals."

source:
  repo: "NVIDIA-DOCA/doca-skills"
  path: "skills/libs/doca-argp/SKILL.md"
  branch: "main"
  license: "Apache-2.0 AND CC-BY-4.0"

provenance:
  scan_run_id: "TBD-at-sign-time"      # NVCARPS scan run UUID
  signed_at:   "TBD-at-sign-time"      # ISO-8601 timestamp from NVCARPS
  upstream_catalog: "https://github.com/NVIDIA/skills"
  upstream_component: "doca"           # see components.d/doca.yml

quality:
  baseline:
    verdict: "PASS"
    blocker_findings: 0
    suite:    "runner/reports/2026-05-26_r15_full_e2e"
    aggregate: "runner/reports/2026-05-26_r15_full_e2e/aggregate.json"
    summary:   "runner/reports/2026-05-26_r15_full_e2e/summary.md"
  regression_contract:
    file:    "runner/baseline_grades.json"
    rule:    "no PASS->FAIL on variant C since last green run"
    gate:    "ci/check-no-regression.py --variant C"

behavior_boundaries:
  documentation_only: true             # bundle ships no runnable code
  hardware_touching_changes_routed_to: "skills/doca-hardware-safety/"
  version_policy_routed_to: "skills/doca-version/"
  external_productized_software_routed_to: "skills/doca-public-knowledge-map/"
  see_also:
    - "AGENTS.md"                       # universal rules
    - "AUTHORING.md"                    # per-skill class-shape contract
    - "BENCHMARK.md"                    # how this skill is graded
    - "SECURITY.md"                     # safety-bug intake

contact:
  bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues"
  safety_bug_intake: "https://github.com/NVIDIA-DOCA/doca-skills/issues/new?labels=safety-bug"
  security:   "https://www.nvidia.com/en-us/security/"

# DOCA Arg Parser workflows

**Where to start:** The verbs run `configure → build → modify →
run → test → debug`. Skip ahead only when the user is already
past a verb. Enter `## debug` directly from any `doca_argp_*`
error or CLI misbehavior. The `## test` verb is an iterative
loop (presence / register / `--help` listing / smoke-parse /
JSON-config), not a one-shot pass — see the eval-loop overlay
in `## test` below.

Read this file when the loader sent you here from
[SKILL.md](SKILL.md). For the param-registration model, the
parameter-type set, the standard DOCA CLI surface, the
`--json <path>` (`-j <path>`) rule (note: the real flag is
`--json`, NOT `--json-config` — do not invent the longer name),
the error taxonomy, observability,
and the safety / path-selection policy, see
[CAPABILITIES.md](CAPABILITIES.md). For the cross-library DOCA
patterns layered under everything below (the canonical
`pkg-config` + meson build pattern, the universal
modify-a-shipped-sample workflow, the cross-library
`DOCA_ERROR_*` taxonomy), see
[`doca-programming-guide`](../../doca-programming-guide/SKILL.md).

Each verb below describes the **shape of the workflow**, not a
copy-paste recipe. The agent's job is to walk the user through
the steps in order, verifying preconditions before recommending
the next call.

## configure

Goal: confirm doca-argp is installed and usable, pick the
shipped-sample `*_main.c` that already wires the Arg Parser, and
plan the register-before-start lifecycle for any new params
before any code change.

Steps the agent should walk the user through:

1. **Confirm the installed DOCA version and that doca-argp is
   present.** Run `pkg-config --exists doca-argp` first
   (presence); if it succeeds, follow with
   `pkg-config --modversion doca-argp` (version). Quote the
   version observed; do not assume "latest". The four-way
   match rule lives in
   [`doca-version CAPABILITIES.md ## Version compatibility`](../../doca-version/CAPABILITIES.md#version-compatibility);
   if the observed sources disagree, route there before any
   Arg-Parser diagnosis. If `--exists` fails, the user's
   install profile does not include doca-argp — route to
   [`doca-setup TASKS.md ## configure`](../../doca-setup/TASKS.md#configure).
2. **Locate the canonical reference: any sample's
   `*_main.c`.** doca-argp ships no dedicated sample tree;
   the reference is the `*_main.c` file in every sample
   under `/opt/mellanox/doca/samples/<library>/<sample>/`.
   Pick one whose other-library context already matches the
   user's intent (e.g.
   `doca_dma/dma_local_copy/dma_local_copy_main.c` when the
   user is modifying a DMA sample's CLI, or
   `applications/dma_copy/` for the reference *application* —
   `samples/doca_dma/dma_copy/` does not exist as a sample
   directory in the public DOCA install; the public samples
   are `dma_local_copy`, `dma_copy_dpu`, `dma_copy_host`) so
   the surrounding code is familiar.
3. **Sketch the lifecycle on paper before writing code.** Per
   the lifecycle table in
   [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes):
   `doca_argp_init` is the FIRST `doca_argp_*` call; every
   `doca_argp_register_param` must run BEFORE
   `doca_argp_start`; `doca_argp_start` runs ONCE;
   `doca_argp_destroy` runs on every exit path including
   error paths. Walking this on paper before editing
   `<sample>_main.c` is the cheapest way to avoid the
   `DOCA_ERROR_BAD_STATE` first-app failure mode.
4. **Plan the new params (if any) by type.** For each
   user-added flag, decide its parameter type per the
   parameter-type table in
   [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
   (`STRING`, `INT`, `BOOLEAN`, `DEVICE`, `DEVICE_REP`, or
   `DOUBLE`). JSON config is a separate input surface, not a seventh
   type. The type choice drives both argv validation and JSON-config
   validation; getting it wrong surfaces later as
   `DOCA_ERROR_INVALID_VALUE`.
5. **Confirm the standard surface is preserved.** The sample's
   existing `*_main.c` already registers the standard DOCA
   CLI flags (per the standard-surface table in
   [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)).
   The user's modification adds rows; it does not replace
   them. The agent must surface this rule before any code
   change.

If any step fails with a `DOCA_ERROR_*`, route through the
error taxonomy in
[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
before taking corrective action. Arg Parser errors are deterministic
authoring/operator failures; do not retry them unchanged.

## build

Goal: compile a doca-argp-using consumer against the user's
installed DOCA, with `pkg-config` as the source of truth for
include + link flags.

The build pattern for any DOCA C/C++ consumer is **identical**
across libraries — `pkg-config` for include + link flags, meson
or CMake as the build system — and is fully documented in
[`doca-programming-guide TASKS.md ## build`](../../doca-programming-guide/TASKS.md#build).
This skill carries only the Arg-Parser-specific overlay:

| Slot | Value for Arg Parser | Why it matters |
| --- | --- | --- |
| `pkg-config` module name | `doca-argp` | The library's `.pc` file installed by the DOCA host packages. Wrong module name = `pkg-config: Package 'doca-argp' was not found`. Presence is profile-dependent; confirm with `pkg-config --exists doca-argp` per [`## configure`](#configure) step 1 |
| Include flags | `pkg-config --cflags doca-argp` | Resolves to `doca_argp.h` under $(pkg-config --variable=includedir doca-common) |
| Link flags | `pkg-config --libs doca-argp` | Pulls in whatever `pkg-config --libs` resolves on this install (do not predict the `-l<name>` form by hand — `.so` basenames use underscores, `.pc` names use hyphens, and `pkg-config` is the only correct translator) |
| Header check | the artifact's public header resolvable under whichever include directory `pkg-config --cflags` reports (do not hardcode the include path — the install layout can move) | If `pkg-config --cflags doca-argp` resolves but the include is missing, the install is partial — route to [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug) layer 2 |
| Companion libraries | Always paired with the user's actual DOCA library (`doca-dma`, `doca-comch`, `doca-rdma`, …) — doca-argp alone does no DOCA work | Building doca-argp into a binary that calls no other `doca_*` symbol is a path-selection mistake; re-read the *Do not use doca-argp when …* column in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) |

For non-C consumers (Rust, Go, Python), the wrapper consumes
`libdoca_argp.so` through FFI; the build-time version
visibility goes through the language's own FFI generator (e.g.
`bindgen` against `doca_argp.h`). The lifecycle and
parameter-type rules still apply — the wrapper consumes a
`*.so` that has its own runtime version per
[`doca-version CAPABILITIES.md ## Version compatibility`](../../doca-version/CAPABILITIES.md#version-compatibility).

## modify

Goal: take a shipped DOCA sample's `*_main.c` as the verified
starting point and apply a **minimum-diff modification** to add
/ remove / rename a CLI flag without breaking the standard
surface.

The universal modify-a-shipped-sample workflow lives in
[`doca-programming-guide TASKS.md ## modify`](../../doca-programming-guide/TASKS.md#modify).
Use it as-is. The Arg-Parser-specific overlay is the
*modify-from-sample schema fill* — the slots the agent must
elicit from the user before recommending any code-level edit:

| Slot | What the agent asks the user | Arg-Parser-specific consideration |
| --- | --- | --- |
| 1. Starting sample | Which `*_main.c` under `/opt/mellanox/doca/samples/<library>/<sample>/`? | Pick the closest in *library context* (a DMA modification starts from a DMA sample's `*_main.c`); the Arg Parser usage is structurally identical across libraries, but the surrounding setup code matters |
| 2. Long + short name | What long name (e.g. `--my-flag`) and (optional) short name? | Long name MUST NOT collide with the standard surface in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) (`--device`, `--representor`, `--rep-list`, `--json`, `--sdk-log-level`); colliding silently overrides the standard flag in `--help` and breaks cross-sample muscle memory |
| 3. Parameter type | Which of `DOCA_ARGP_TYPE_STRING`, `_INT`, `_BOOLEAN`, `_DEVICE`, `_DEVICE_REP`, or `_DOUBLE` applies (per the parameter-type table in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes))? JSON config is not a type. | The choice determines both argv validation and JSON-config validation; declaring an `int` and then passing `0x40` surfaces as `INVALID_VALUE` per [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) |
| 4. Value-callback target | Which user-config struct field does the parsed value write into? | The callback runs DURING `doca_argp_start`; do not call back into `doca_argp_*` from inside it (that's the most common `BAD_STATE` first-app failure) |
| 5. Description for `--help` | What one-line description should `--help` show for the new flag? | The description is what the operator reads; vague descriptions surface as user-confusion bug reports, not as parser bugs |
| 6. JSON-config impact | Does the user want operators to be able to set this from `--json <path>` as well? | Every registered param is automatically settable via the JSON file using the long name as the key — the user does not have to register it twice, but does need to communicate the key to operators |
| 7. Build manifest | Keep the sample's existing `meson.build` (which already wires `pkg-config doca-argp` via the parent sample build) | Yes. Do not switch to a hand-rolled Makefile for *"simplicity"* — it removes the version-check rail and breaks the standard build pattern |

The agent's anti-pattern alert: a *"swap doca-argp for getopt
because it'll be simpler"* refactor is **always** a regression
on a shipped sample — it breaks the standard CLI surface, drops
the `--json` integration silently, and removes the
error-taxonomy ladder in
[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
Per [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy),
the agent must refuse this refactor and explain why before
producing any diff.

## run

Goal: execute the built binary against the user's installed
DOCA and confirm both the new flag and the standard surface
parse correctly.

Steps the agent should walk the user through:

1. **First run: `./<binary> --help`.** Confirm the operator-side
   listing shows the standard surface (`--device`,
   `--representor`, `--rep-list`, `--json`,
   `--sdk-log-level`) AND the user's new flag with the
   description from
   [`## modify`](#modify) slot 5. If the new flag is missing,
   registration never happened (likely a missing
   `doca_argp_register_param` call); if the standard flags are
   missing, `doca_argp_init` was skipped or replaced. Per
   [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability),
   `--help` is the cheapest first signal.
2. **Second run: argv smoke.** Invoke
   `"$BINARY" --device "$PCI" --my-flag "$VALUE"` after assigning
   each variable from the user's actual value without `eval`.
   Confirm the
   binary parses successfully and reaches its first
   non-Arg-Parser code path. A parse failure at this stage is
   one of the `DOCA_ERROR_*` rows in
   [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
3. **Third run: JSON-config smoke.** Author a small
   `./my-config.json` with the user's new flag as a key plus
   one or two standard-surface keys (e.g. `"device":
   "0000:03:00.0"`), then invoke
   `./<binary> --json ./my-config.json`. Confirm the
   binary parses the same set of values it parsed in step 2.
   This confirms the JSON-config path covers the new flag,
   which is the load-bearing reason to reuse doca-argp.
4. **Capture the structured log on first failure.** Set
   `DOCA_LOG_LEVEL=trace` (see
   [`doca-debug CAPABILITIES.md ## Observability`](../../doca-debug/CAPABILITIES.md#observability))
   when any of the above three runs fails; the trace shows
   the per-param parse calls and surfaces the
   `--json` file read.

For the runtime version + `LD_LIBRARY_PATH` cross-checks that
underlie *"the program built but does nothing"*, see
[`doca-version TASKS.md ## run`](../../doca-version/TASKS.md#run).

## test

Goal: prove a doca-argp-using consumer is correct end-to-end —
the new flag works, the standard surface still works, and the
JSON-config path covers both — before claiming the *"wire
doca-argp into this sample"* journey is done.

This is **a loop, not a one-shot pass.** Each iteration narrows
either the registration shape, the parameter type, the standard
surface coverage, or the JSON-config coverage. The loop
terminates when the user reports a `--help` smoke + an argv
smoke + a JSON-config smoke all pass AND the standard-surface
flags still behave the same as in a sibling unmodified sample.

Iteration shape:

1. **`--help` listing.** Confirm every registered param
   (standard surface + user-added) appears with its
   description. Missing rows mean registration never happened;
   extra rows mean a stale registration was not removed.
2. **Argv smoke for the new flag.** Pass the new flag with a
   valid value; confirm the value-callback fires and writes
   into the user-config struct as expected. Add a one-line
   log inside the callback per
   [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability)
   signal 2 if the callback's effect is hard to observe.
3. **Argv smoke for the standard surface.** Re-run the
   sample with the standard flags only (`--device <PCI>` and
   any sibling-sample-mandatory flag) and confirm the
   sample's pre-modification behavior is intact. If the
   standard flags broke after the user's diff, the
   modification overrode a default registration.
4. **JSON-config smoke.** Drive the same configuration from
   `--json ./my-config.json`; confirm argv-equivalent
   behavior. An unknown JSON key surfaces as
   `DOCA_ERROR_NOT_SUPPORTED` (pedantic parsing) per
   [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
   — that's a JSON-file typo or a stale config, not a
   library bug.
5. **Cross-version run** (if the user has multiple installs):
   re-run steps 1-4 on each install; quote the version per
   [`doca-version TASKS.md ## configure`](../../doca-version/TASKS.md#configure)
   in the report.

Eval-loop overlay — why this is a loop, not a one-shot pass:

| Iteration trigger | What it looks like | What changes next iteration |
| --- | --- | --- |
| `--help` does not show the new flag | The new flag's `doca_argp_register_param` either never ran or ran AFTER `doca_argp_start` | Re-walk the lifecycle table in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) and move the register call before `_start` |
| `--help` shows the new flag but argv smoke returns `DOCA_ERROR_INVALID_VALUE` | The registered parameter type does not match the value the user passed | Re-check the parameter-type table in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes); fix on the registration side OR the operator side, not both |
| Argv smoke passes; JSON-config smoke returns `NOT_SUPPORTED` | The JSON key is not the long name of any registered param (typo, or a renamed flag the JSON file did not catch up with) | Diff the registered long names against the JSON keys; rename whichever side is wrong |
| JSON-config smoke returns `IO_FAILED` | The path is wrong, the file is unreadable, or the JSON is malformed | Resolve at the OS layer (`ls -l <path>`; `cat <path> \| jq .`) before any code change |
| Standard surface broke after the modification | The user's diff overrode a default `doca_argp_init` registration (e.g. re-registered `--device` with a different callback) | Remove the redundant registration; the standard surface is owned by `doca_argp_init` and should not be re-registered |
| Same code passes on host A, fails on host B | Different DOCA version or different install profile (doca-argp not installed on host B) | Re-run [`## configure`](#configure) step 1 (presence + version) + [`doca-version TASKS.md ## test`](../../doca-version/TASKS.md#test) four-way match on host B |

Loop termination: an iteration's identity is its trigger-table row
plus the captured `DOCA_ERROR_*`/output. Run the sweep once and permit
at most one corrective mutation and rerun. If the second sweep is
still non-green, stop regardless of symptom changes and escalate to
[`doca-debug TASKS.md ## debug`](../../doca-debug/TASKS.md#debug)
with the captured `--help`, argv-smoke, and JSON-config-smoke
evidence.

## debug

Goal: when a `doca_argp_*` call returns a `DOCA_ERROR_*` (or
the program's CLI silently misbehaves), narrow the cause to a
specific layer before recommending any code change.

The cross-library debug ladder lives in
[`doca-debug TASKS.md ## debug`](../../doca-debug/TASKS.md#debug).
Walk through it in order — install → version → build → link →
runtime → program → driver — *before* recommending
Arg-Parser-specific fixes. This skill's overlay names the
Arg-Parser-specific manifestation at layer 6 (program); the
library does not own runtime / driver layers because it has no
hardware accelerator behind it.

**Layer 6 (program) — Arg Parser overlay.**

- **Lifecycle order is the first hypothesis.** Per the
  lifecycle table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes),
  the most common first-app failure is registering a param
  after `doca_argp_start` (returns `BAD_STATE`), or calling
  `_start` twice in the same process. Walk the user's
  `*_main.c` against the lifecycle before looking elsewhere.
- **Type mismatch is the second hypothesis.** A flag that
  registers cleanly but rejects the operator's value with
  `DOCA_ERROR_INVALID_VALUE` is a type mismatch between the
  registered parameter type (per the parameter-type table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes))
  and the value the operator wrote. The fix is on the
  declaration side OR the operator side, not a retry.
- **Unknown JSON key is the third hypothesis.**
  `DOCA_ERROR_NOT_SUPPORTED` from `doca_argp_start` when
  `--json <path>` is in play (pedantic parsing) means the JSON
  file references a long name no registered param uses. Diff the
  registered long names against the JSON keys; one side is
  stale.
- **Unreadable JSON file is the fourth hypothesis.**
  `DOCA_ERROR_IO_FAILED` is an OS-layer problem (missing
  file, wrong permission, malformed JSON). Resolve via
  `ls -l <path>` and `cat <path> | jq .` before any code
  change.
- **Standard surface override is the fifth hypothesis.** If
  the user's modification broke a standard flag's behavior,
  the diff re-registered a name `doca_argp_init` already
  owns; remove the redundant registration.

Once the layer is identified, route to the matching debug verb
on the matching skill: install / build / link to
[`doca-setup ## debug`](../../doca-setup/TASKS.md#debug);
version to
[`doca-version ## debug`](../../doca-version/TASKS.md#debug);
cross-cutting runtime to
[`doca-debug ## debug`](../../doca-debug/TASKS.md#debug);
program-layer Core-context patterns (in the *downstream* code
the parsed values feed into) to
[`doca-programming-guide TASKS.md ## debug`](../../doca-programming-guide/TASKS.md#debug).

## Deferred task verbs

The following verbs are out of scope for this skill but are
commonly asked in the same conversations. Route them as follows
so the agent does not invent guidance:

- **install.** Installing DOCA, choosing packages, post-install
  verification, `pkg-config` wiring — defer to
  [`doca-setup`](../../doca-setup/SKILL.md) and to the
  install-tree layout in
  [doca-public-knowledge-map ## Layout of an installed DOCA package](../../doca-public-knowledge-map/SKILL.md#layout-of-an-installed-doca-package).
  This skill assumes DOCA is already installed.
- **deploy.** Deploying doca-argp-using applications at scale
  (sample CI, distributing JSON-config files to operators) —
  out of scope for Phase 1.
- **manage / monitor.** Per-operator CLI usage analytics or
  config-file change auditing — outside doca-argp's surface;
  the library parses, it does not telemeter.
- **shell-completion generation.** Out of scope; the Arg Parser
  exposes `--help` but does not emit bash / zsh completion
  scripts. Operators wanting completion can layer a
  language-native completion generator on top.

## Command appendix

Every command below is **cross-cutting on DOCA Arg Parser** — it
answers a recurring class of question that comes up in the
verbs above. The agent should treat the *class* as
load-bearing; the worked example is a single instance. Run-as
user is the unprivileged user unless noted. Sudo is called out
per row.

**Infra-aware preamble (every row below).** Per the bundle's
detect → prefer → fall back → report contract documented in
[`doca-structured-tools-contract ## The agent behavior contract`](../../doca-structured-tools-contract/SKILL.md#the-agent-behavior-contract),
the agent should:

1. Probe for the matching structured helper FIRST (`doca-env --json`
   for version + libraries + sample paths in one shot;
   `version-matrix.json` for *"available since"* lookups).
2. If the probe succeeds, the structured tool's output is the
   authoritative answer and the agent SHOULD NOT also run the
   manual command in the row below. Report *"using structured
   `<tool>`"*.
3. If the probe fails, fall back to the manual command in the
   row. Report *"falling back to manual chain"*.
4. The schemas the structured tools emit are defined in
   [`doca-structured-tools-contract ## Schemas`](../../doca-structured-tools-contract/SKILL.md#schemas);
   the version-handling semantics (four-way match, NGC,
   headers-win) are owned by
   [`doca-version`](../../doca-version/SKILL.md).

| Command (worked example) | Owning step | Class of question it answers | What healthy output looks like |
| --- | --- | --- | --- |
| `pkg-config --exists doca-argp && echo ok` | `## configure` step 1 | Is the Arg Parser installed in this DOCA install profile at all? | `ok`. A non-zero exit = doca-argp not present; route to [`doca-setup TASKS.md ## configure`](../../doca-setup/TASKS.md#configure) |
| `pkg-config --modversion doca-argp` | `## configure` step 1; `## build` slot 4 | What is the build-time Arg Parser version? | A semver string matching `doca_caps --version`. Disagreement = partial install (route to [`doca-version TASKS.md ## debug`](../../doca-version/TASKS.md#debug) layer 2) |
| `pkg-config --cflags --libs doca-argp` | `## build` | What include + link flags does the linker need? | Trust whatever `pkg-config --cflags --libs` produces on this install. Do not hardcode either the `-I` include path or the `-l<name>` flag form — both can drift between DOCA install profiles and DOCA majors; the on-disk `.so` basenames use underscores on every release where we have ground truth, while the `.pc` package names use hyphens, and `pkg-config` is the only thing that resolves both correctly. Hand-crafted `-l` lines silently break when DOCA upgrades. |
| `ls /opt/mellanox/doca/samples/*/*_main.c \| head` | `## configure` step 2; `## modify` slot 1 | Which sample `*_main.c` files ship in this install, and which is the closest starting point for a CLI modification? | A list of `*_main.c` paths, one per shipped sample. Pick the closest in library context |
| `"$BINARY" --help` | `## run` step 1; `## test` step 1 | Does the built binary's `--help` listing show the standard DOCA CLI surface plus every newly registered param? Assign `BINARY` without `eval` and keep the expansion quoted. | A help listing with `--device`, `--representor`, `--rep-list`, `--json`, `--sdk-log-level`, plus every user-added flag with its description |
| `jq . -- "$JSON_PATH"` | `## run` step 3; `## debug` layer 6 | Is the `--json` file valid JSON before we blame doca-argp for `IO_FAILED`? Assign `JSON_PATH` from the user value and keep it quoted. | A pretty-printed JSON tree. A `jq` parse error = malformed JSON, fix the file before any code change |
| `DOCA_LOG_LEVEL=trace "$BINARY" --json "$JSON_PATH"` | `## run` step 4; `## debug` layer 6 | What did the structured DOCA logger emit during the Arg Parser parse? Assign both variables without `eval` and keep expansions quoted. | A trace-level line on every per-param parse call and on the JSON-config file read. Silence on a flag = the flag was never registered |

For commands shared across libraries (`pkg-config --modversion`,
`doca_caps`, `cat /opt/mellanox/doca/applications/VERSION`,
`DOCA_LOG_LEVEL`) the cross-library overlay is in
[`doca-debug TASKS.md ## Command appendix`](../../doca-debug/TASKS.md#command-appendix);
this table adds the Arg-Parser-specific rows on top.