# Teach your agent how you work Source: https://www.hyperagent.com/docs/guides/teach-your-agent-how-you-work > For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL. Turn your process, judgment, and quality standards into a skill your agent can use on new jobs. You know which questions to ask, what to check, and what makes a result worth using. Turn that know-how into a skill so your agent has a method to follow when the customer, source material, or situation changes. ## Start with something you can show [#start-with-something-you-can-show] Choose a job you know well and a result you would be happy to use again. Bring the agent an example, your checklist, or a document that explains your approach. You can also work through the job together and use your corrections to build the method. Explain **why the example works**. A finished quote shows the price and terms; it may not reveal how you checked the rate sheet, spotted missing information, or decided what needed approval. Those choices belong in the skill too. ## What can you teach your agent? [#what-can-you-teach-your-agent] A skill can describe more than a sequence of steps. These examples show how to turn a way of working into concrete instructions. They illustrate approaches you can combine in your own skills, not built-in skill categories. ### A process to follow [#a-process-to-follow] A report refresh needs more than “get the latest numbers.” A reporting method defines the order of work and when the result is ready to share. ```markdown title="Report refresh" # Refresh the report 1. Retrieve the source data for the requested period. 2. Run independent queries before work that depends on them. 3. Retrieve all result pages before assembling the report. 4. Check the assembled data, then build the report. # If a check fails Stop publication when a required check fails. Explain warnings and any information that could not be retrieved. Do not present a partial refresh as a complete report. ``` ### A way to weigh the options [#a-way-to-weigh-the-options] Tell the agent what matters when choosing between options. It should explain its choice, show the facts behind it, and point out what you give up by choosing it. ```markdown title="Choose an option" # Understand the choice Explain what we need to choose and what matters most. Ask if the priorities are unclear. Use current facts. If sources disagree, show where they differ. # Recommend an option Say which option you would choose and why. Link to the facts behind your choice. Show the next-best option and when it would be a better fit. Point out any missing information that could change the answer. ``` ### Standards to check against [#standards-to-check-against] “Research this applicant carefully” leaves too much unstated. An applicant-review method makes evidence quality visible and checks that the recommendation stays consistent wherever it is recorded. ```markdown title="Evidence review" # Check the evidence Distinguish facts, inferences, and unknowns. Link factual claims to their sources. Show missing information as unknown instead of omitting it. # Check the handoff Keep the recommendation, confidence, and rationale consistent across the report, tracker, and summary message. Read updated records back to confirm what was saved. Do not overwrite a human decision with your recommendation. ``` ### A consistent way to use a tool [#a-consistent-way-to-use-a-tool] A tool can finish successfully while its output is still wrong. This video workflow uses attached scripts to check the render, then asks the agent to inspect what viewers will actually see. Attached scripts: verify_geometry.py inspect_render.py ```markdown title="Video verification" # Prepare the render Check the installed tool version before choosing commands. Confirm images are valid and fonts have loaded. # Use the attached scripts Run verify_geometry.py to check the layout geometry. Run inspect_render.py to inspect the encoded output. Read their usage instructions before choosing arguments. Report failed checks and fix the cause before rerunning. # Review what the scripts cannot prove Check the finished file’s dimensions and duration. Inspect the actual first frame, last frame, and key transitions. Do not assume the inspection script checks the exact endpoints. Play the video in the page where it will be viewed. Confirm playback advances and the controls work. A successful render command alone does not mean the video is ready. ``` ### A format that serves the reader [#a-format-that-serves-the-reader] The right format depends on what someone needs to do with the result. An attached script can suggest a page template; the skill tells the agent how to choose and fill it. Attached script: pick_template.py ```markdown title="Document structure" # Choose the format State the reader’s goal in one sentence. Read the usage instructions for pick_template.py, then run it to suggest a template for that goal. Treat its suggestion as a starting point, not a final decision. Read the selected template before drafting. To explain a distinction: Describe the situation, what each option means, and what changes when the reader chooses one. To help someone complete a task: Give prerequisites, actions, the expected result, and what to do if something goes wrong. To help someone find an exact answer: Use consistent reference entries with clear labels. # Check the page Give it one primary job. Include enough context for someone arriving directly from search. ``` ## Turn your approach into a skill [#turn-your-approach-into-a-skill] ### Show the agent a good example [#show-the-agent-a-good-example] Give it a result you trust and the sources used to produce it. Explain who the result is for and what they need to do with it. If you already worked through the job in a thread, start there. ### Explain the decisions behind it [#explain-the-decisions-behind-it] Point out the checks, exceptions, and choices that are not obvious from the finished work. Ask the agent to identify gaps in the method and ask you about them before filling them in. ### Ask the agent to save the method [#ask-the-agent-to-save-the-method] Have it write the skill’s purpose, when to use it, required inputs, method, expected output, and checks. Review any pending skill card and confirm the skill was saved. See [Edit and import skills](https://www.hyperagent.com/docs/concepts/skills/skills-edit-and-import) for saving or bringing in an existing method. ### Try it on a different case [#try-it-on-a-different-case] Make the saved skill available through the agent’s [knowledge settings](https://www.hyperagent.com/docs/concepts/agents/knowledge-access). Start a fresh thread with that agent, supply new inputs, and ask it to read the skill and do the job. Check whether the method holds up without repeating your earlier corrections. Use the work and feedback in this thread to create a reusable skill. Explain when to use it, which inputs it needs, the steps and decisions to follow, what the result should look like, and how to check it. Ask me about important choices that the example does not explain. Keep customer-specific facts and temporary deadlines out of the reusable method. Save useful examples as reference material and any reusable code as scripts with the skill, explaining when to use each. Show me what needs review, confirm what was saved, and suggest a different case we can use to test it. ## Make your guidance specific enough to follow [#make-your-guidance-specific-enough-to-follow] **Explain what to look for and what to do next.** * “Check each requested item against the rate sheet. List anything without a matching price as a question.” * “Lead with the recommendation, then explain the tradeoff and link to the evidence.” * “If the customer record is ambiguous, ask before updating it.” **Leave the important choices unstated.** * “Make an accurate quote.” * “Write a professional report.” * “Use your best judgment to update the CRM.” You do not need to prescribe every sentence. Be precise about the decisions and checks that matter, and leave room for the agent to adapt to the job. ## Keep the method and its supporting material together [#keep-the-method-and-its-supporting-material-together] A short skill may only need instructions. The recommendation example needs no attached scripts or reference files. Add those supporting materials when they make the method easier to follow. Instructions The method itself: when it applies, what to do, how to handle exceptions, and what counts as finished. Reference material Examples, templates, or detailed documentation the agent can read when needed. Explain which reference helps with which part of the job. Supply this customer’s facts with the task rather than making them part of the reusable method. Scripts Code for repeatable calculations, data cleanup, or file formatting. Your agent can write and test it, save it with the skill, and document when to run it. See [using scripts](https://www.hyperagent.com/docs/guides/where-instructions-belong#use-scripts-for-work-that-needs-exact-rules) for examples. A quote-preparation skill can include both the steps and the checks for a quote. If the same writing-review method is useful for quotes, emails, and reports, it may deserve its own skill. Give each skill a clear purpose so the agent can tell when to use it. ## Check whether the skill works beyond the example [#check-whether-the-skill-works-beyond-the-example] * **New inputs:** does it handle a different customer or source file without reusing the original facts? * **Missing information:** does it ask or flag the gap rather than inventing an answer? * **The right method:** did it read and follow the skill’s full instructions, not just find its summary? * **A usable result:** does the output meet the stated checks, with sources or verified calculations where needed? When it misses something, improve the relevant instruction or example in the skill. Test again on a fresh case to see whether the correction helped. Success means you can give the agent a new case and spend your feedback on the substance of the result. The skill carries the steps, decisions, and checks you would otherwise have to explain again. For how the skill fits with the agent’s role and standards, see [Make your agent’s good work repeatable](https://www.hyperagent.com/docs/guides/where-instructions-belong).