AI Prompts, Roles, and Skills

Definitions

Let's start with defining the terms used with these functions. In the AI library settings, you can create and edit three types of AI-related functions: prompts, roles, and skills.

Prompts: Though we may not use the term, we are all very accustomed to prompts. These are the things we tell AI to do. "Search online information about skunks, both scientific and casual. Return at least 20 useful results. Present them in an HTML document with all references linked."

Prompts require a Keyword and Instructions. The keyword tells AI to run the task in the instructions. Use when merely provides a description of what the task does.

Roles: While optional, a role is a persona used by the AI to steer the responses. At times, we need a more focused reply, e.g., when building information for young people or even needing a layperson's view on subjects you are unfamiliar with. When using a role, that persona is loaded and will filter and steer AI's replies based on that role. For example, "You are an expert nature writer, combining science and beautiful prose in a way that appeals to people, from academics to nature lovers."

You can define as many roles as you need and even call them from a prompt or skill. Imagine you are creating a series of pamphlets for a nature center. You could have a role to write for young children, one for teens, and another for adults. If you need a specific style, roles are a good choice.

Roles require a Keyword and Instructions. The keyword "loads" the role for the subsequent prompts. Use when is merely descriptive, the situation where the role could be used.

Skills: Skills are an instruction set, defining a task to accomplish. It is a series of prompts given to the AI to follow. Unlike scripting, the AI has the ability to make decisions about the steps, even do some multiple times as it refines the information to pass on to its next steps. As you can see in the built-in skills, there are examples of organizing, creating digests and summaries, building Wiki pages, etc. Also note skills can make use of DEVONthink's MCP server, regardless if it's enabled in the AI > Chat settings.

The options are seemingly unlimited here as uses will often be very specific to your own situation. But following our running example, you could create a skill like "Find documents in this database related to @. Write the copy for a pamphlet using the child role, then the teen role, then the adult role. Output each as individual HTML documents, styled with nature colors, and softer fonts."

At a minimum, skills use a Keyword, Instructions, a Context, and Tools. Use when allows AI to run the skill from interpreted prompts instead of explicitly using the keyword. It is required if you want to enable Let the assistant use this on its own.

Keywords: With each function, you can assign a keyword, also called a slash command. This is a shortcut for running any of the functions, e.g., in the Chat assistant or calling a prompt in AI-specific smart actions. And take note of a special placeholder used in the instructions of a prompt or skill, %@, and it represents something you've typed after the slash command. Imagine a prompt of "Search for information about %@ in the Nature database." with a keyword of /nat-writing. If you opened the Chat assistant and typed, /nat-writing pheasants, it would search for pheasants. Similarly, you could as the placeholder to denote a number of items, e.g., with a small change to the prompt, /tags 8 would suggest eight tags.

Creating an AI function

Designing your own function is a new process for many people. Fortunately, there are practical examples built in so you can examine, duplicate, and modify them, as needed. However, let's walk through manually creating a skill to generate a simple report from receipts in a My Finances database.

• Start with the idea: Examine receipts in a given time period to determine how much I spent and on what.
• New > Skill: Finance View
• Keyword: /fin-view
• Use when: user asks for a monthly summary of finances in a certain timeframe
• Instructions: Tell the AI what to work on and what the task requires.

• Context: Nothing as we provide a date to look at when the skill is called.
• Tools: Read & edit contents since AI needs to examine each document and create an output document.
• Let the assistant use this on its own: Enabled so AI can interpret a prompt and run the skill.
• Ask before automatic use: Disabled so it can run unattended.
• Isolated run (send without chat history): This is optional but enabling it does allow you to choose a specific AI model to execute the tasks.

Now you have a skill you can call by typing /fin-view followed by a date or even asking, "What was my spending last month?"

AI Assistance: In addition to being your library of AI functions, you can also use AI to create these items for you. When you create a new skill, you can manually enter your the instructions, etc. if you are familiar with the process. Otherwise, enter some explanatory text in the editing field at the top right, either a new idea or changes you'd like to make to an existing function. Then press the Edit button (or Generate for new functions) and the keyword, use field, and instructions will be populated for you.

As skill creation is new for many people, describing your task to AI and letting it build the skill for you is a good way to get started. Even if you have some experience, you can ask AI to assess and improve on a skill you've created.

Using scripts in skills: When creating a skill, you can prompt AI to create scripts, AppleScript and JavaScript for Automation (JXA), if needed for the skill. For example, you may have a skill that gathers certain files but you need it to produce a ZIP file to send to someone. Instruct it to create and use a script as part of the skill. After the script is created, you will see a icon next to the Tools popup. Clicking on it opens a popover where you can open the Skills directory, reveal the script, or open the script in the default script editing application.

Scripts in skills typically use the Script with Input/Output syntax discussed in the smart item scripts section of this chapter.

If DEVONthink is enabled to use iCloud Drive, these scripts will be stored in a DEVONthink/Skills folder in iCloud Drive and will sync to your other Macs. If DEVONthink isn't enabled to use iCloud Drive, the scripts are stored in the ~/Library/Application Script/com.devon-technologies.think/Skills directory. These scripts should be saved as text, not compiled – .applescript or .js – and use a hyphen-delimited name. In the skill's instructions, you can call a script using a form like Use run_script "/Skills/my-fancy-script.applescript" on the selected records.

Sharing: Exporting any of these functions yields a .dtSkill file, containing the parameters and settings. For skills, any associated scripts are included as part of the export, so there's nothing to manually install when importing on a different machine.