Practice guide
Build a reusable skill
Turn a successful workflow into instructions another engineer can run and verify.
Start with a workflow that already helped
Use this guide in Guardrails after a useful workflow has worked on real tickets. Bring its instructions, one reviewed change, the checks that caught problems, and the repository conventions it depends on. A reusable skill should tell another engineer when to use it, what to supply, what to do, and how to judge the result.
Choose a narrow task such as reviewing workspace authorization. Keep the first version small enough to run during ordinary delivery. A long collection of general advice is difficult to test or improve.
Build, test, and transfer it
- Extract the repeatable steps. Separate decisions specific to the original ticket from checks that apply again. Keep links to the relevant policy, code, and tests so users can verify the instructions.
- Define the contract. Name the trigger, required inputs, expected evidence, stop conditions, and responsible owner. Record a version and the repository context in which you checked it.
- Run it on a second change. Ask another engineer to follow the written instructions. Observe missing inputs, ambiguous steps, and whether the evidence actually supports the conclusion.
- Repair and review. Update the instructions from that run. Keep human review and existing test, security, and release controls in the workflow. A completed checklist alone does not establish that access controls work.
- Transfer it. In Scale, give the receiving pod the skill and a representative task. Let them run it without the original author steering every step. Record their corrections and the version they used.
Worked example: authorization review
- Trigger
- A change reads or writes a resource belonging to a workspace.
- Inputs
- The ticket, changed routes and service code, authorization policy, resource ownership model, and relevant tests. Supply approved test identities and data.
- Steps
- Trace identity to permission check to resource lookup. Verify the workspace boundary. Inspect each changed entry point. Run allowed-user, denied-user, and cross-workspace checks. Review failure responses and log handling.
- Expected evidence
- Code references for enforcement, test commands and results, any uncovered path, and a reviewer’s disposition of each finding.
- Stop conditions
- Missing policy, unclear ownership, unavailable checks, or a failing boundary test. Record the gap and ask the responsible owner to resolve it before approval.
- Owner and version
- Assign a named engineering owner. Start at version 1 with a review date and the changes used to validate it.
Success is another person using it
Keep the reviewed skill, the second run’s evidence, and its revisions together. It is ready to share when another engineer can use it, explain its limits, and produce a reviewable result. Revisit it when the repository’s authorization model or checks change.
A working document to compare with yoursA reusable authorization skill →