Pinning Claude Skills API Releases
Pin a tested skill version in Claude’s Messages API when downstream software depends on the result. Keep candidate versions in a separate test configuration and promote them after they pass the same checks as the version in production.
Record what the request runs
Configure the Messages API request with the code execution tool and the skill’s type, ID, and explicit version in the container. Anthropic-managed and custom skills use the same request structure. Keep those three values with your application’s release configuration so operators can identify which skill a given release was supposed to run and restore that selection if necessary.
Test the assembled request with a small input whose expected result you can check. Record the requested version, whether the request completed, and whether the output met the application’s contract. A completed request with the wrong output is a failed release check. A request rejected before it produces an output calls for checking the request configuration first.
Keep a copy of the known-good manifest with the acceptance fixture. Restoring an old manifest is a discrete, reviewable operation even when two different skills have changed.
Using Agent Skills with the API - Claude Platform DocsSeparate setup failures from workflow regressions
When a previously passing fixture fails before producing an answer, inspect the request your application actually sent. The Messages API lists skills in container.skills and includes the code execution tool. Managed Agents uses a different attachment point, the agent’s skills array, and can also load skills from a GitHub repository mounted on the session. Check the integration path before changing the skill instructions.
When the call completes but the result regresses, rerun the fixture with the previous version under the same request settings. If the previous version passes, restore that selection and investigate the candidate. If both fail, inspect shared inputs, prompts, and response handling. Pinning gives you a useful comparison point, with the tradeoff that adopting improvements becomes an explicit release step.
Record the exact pin returned by the approved release process. A moving alias can make two identical-looking test manifests exercise different behavior.
Agent Skills - Claude Platform DocsChoose who owns the workflow rules
Start with an Anthropic-managed skill when your requirement is a standard document task. Try it on realistic inputs and judge it against the deliverable you actually need. If your team requires a private decision rubric, a fixed exception policy, or a house template, test a custom skill that carries those instructions and resources. Both choices use code execution in the Messages API.
For a custom skill, put the conditions for using it in the description and the procedure in the instruction body. Test a request that clearly fits, one with ambiguous intent, and one that should take a different path. Judge the result against rules unique to the workflow. A plausible generic answer may still miss the procedure your release is meant to enforce.
Using Agent Skills with the API - Claude Platform DocsTest a version change against a known answer
In an illustrative test, a custom skill summarizes receiving discrepancies. Give both the pinned release and the candidate a shipment with 20 units expected, 17 received, and an escalation threshold of 3 missing units. The expected output is a discrepancy of 3 and an escalation. Run a second fixture with the received count blank. The expected output is a request for the missing value.
Submit the same fixtures to the Messages API with the same code execution setup and prompts, changing only the selected skill version. Compare the values consumed by your application as well as the human-readable summary. If the candidate treats a blank count as zero, update its instructions to handle missing values explicitly and repeat both tests before promotion.
Using Agent Skills with the API - Claude Platform Docs