Attaching a skill, a prompt or a Library item to an agent: what it reads in the next conversation, and how to check

Back to all essays→

This post is for a team lead setting up a first custom agent in Ground Control, with skills, prompts and documents they want it to use. The question is: "When I attach a skill, a prompt or a Library item to my agent, what does it actually get in the next conversation, and how can I check that it used what I attached?" Every product fact below comes from the current product. Where something is not served yet, the post says so.

My view

An attachment is real when you can see it change an answer. The Attachments section shows what you asked for. A test question shows what the agent got. Today the test question is the only proof Ground Control gives you, so it is worth knowing how to ask a good one.

The short answer

• The agent gets the full text. Every attached prompt, skill and Library file is put in front of the model in full, before your message, on every turn. The agent does not search for it, and it does not decide whether to open it.
• Nothing you attach as a file is dropped quietly. If an attachment cannot be read, the turn fails and says which kind it was. The agent does not answer without it.
• A conversation keeps the agent it started with. Changing attachments saves a new revision of the agent. Start a new conversation to use it.

What the agent reads, in order

1. The agent's own instructions, the text you wrote for "What should it do?".
2. Each attached prompt, in the order you set, as its full text.
3. Each attached skill, as "Attached Skill:" and its name, then the skill's full instructions.
4. Each attached Library file, as "Attached Library item:" and its name, its revision and whether it is pinned, then the file's full text.

After these come the conversation so far, any files you added to this message, and then your message. The agent reads all of this again each time it calls the model. That happens at least once per message, and again after each step where it uses a tool.

Which version it reads

• Skills are always pinned. The agent page says: "This Skill is pinned to the revision selected when it was attached." A later edit to the skill does not reach the agent until you save a new agent revision with the newer one.
• Prompts and Library files are pinned by default. When you add one, it is pinned to its current revision. Pinned means: "The Agent keeps using the revision shown here, even after someone publishes a newer revision."
• You can choose Track current instead. Then: "The Agent always uses the current revision, so later published changes apply without another Agent revision." The newest text is read on the next message, even in a conversation that is already open.
• The list of attachments belongs to an agent revision. Save attachments creates a new revision. It becomes the one people talk to when Make this Agent revision current is ticked. A conversation keeps the revision that was current when it started, so a conversation that is already open keeps its old list.
• The agent reads with your access. Attachments are read with the access of the person sending the message. If a teammate cannot read an attached item, their turn fails. The agent does not quietly answer without the item.

What it does not get yet

• Folders. Under Knowledge, the create form lists both folders and files. A file is attached in full. A folder can be saved too, but the form and the agent page say: "Folders are not used in chat yet. Attach files for the agent to read." Today a chat turn reads nothing from it. If you want the agent to use a document, attach the file.
• Large or non-text files. A Library file reaches a chat only as text, up to 32 KiB. A PDF, a Word file or a longer text is refused, never cut short, and the turn fails.
• Skill scripts. Only a skill's written instructions reach the agent. Scripts and other files in the skill are not run or sent in a chat.
• A record of each reply. No screen shows which revision of each attachment a particular reply was given. The chat shows a "Source:" line only for connected files the agent opened during the turn.

If you use the agent in a workflow, the workflow's Agent node has an Effective inputs panel. When it shows a preview, it says "Preview only". It shows what a run of that node is set to get. A chat with a custom agent has no such panel yet.

An example to try: a note only the agent should know

This is a hypothetical example. You can repeat it in any workspace. The owner adds a Library note called Pickup hours: "Pickup is from 8 to 11 on Saturdays." They build an agent called Pickup helper and tell it: "Help customers collect their orders. Use the Pickup hours note for the times." They attach the note as a file, set it to track its current revision, save the attachments and make that revision current. The agent page shows the note attached, with its text.

Then the owner starts a new conversation and asks: "What are your pickup hours?" The right answer names 8 to 11 on Saturdays. Those times are only in the note, not in the instructions, so the answer shows the agent read the note.

If the answer is vague, or the agent says it cannot see the note, the agent page is not enough to tell you why. Common causes are a folder instead of a file, a conversation opened before you saved, or a file that is too large or not text. The checklist below walks through them. One more thing is worth knowing. When an instruction names a document the model was not given, a model may make up a reason it cannot reach it, such as a source that is "not connected". Treat that kind of reply as a sign the text did not arrive, not as a description of your setup.

What I take from it: the agent page tells you what is configured. It does not tell you what the agent got. One plain question shows the difference.

How to check your own agent

1. Open the agent and go to Attachments. Look at Prompt bindings, Skill bindings and Library references. Each prompt and Library file shows Pinned or Tracks current.
2. Use View content on a prompt or Library file to read the text the agent will be given.
3. Attach files, not folders. Keep each file as text, under 32 KiB.
4. After Save attachments, make the revision current, then start a new conversation.
5. Ask one question that only the attachment can answer, with a detail that is not in the instructions. Check the answer against the text.
6. If you ask the agent where an answer came from, its reply is its own account, not a record.
7. If you see "The Agent turn failed because an attached Library item could not be read", check that the item is plain UTF-8 text, under 32 KiB, and readable by the person who sent the message. Prompts and skills have a matching message that names the Prompt or Skill. For those, check that the person can read them.
8. If something changed and you are not sure when, open History and use Compare to see the Diff between two agent revisions.

The agent guide and the quickstart cover setting up a workspace and its agents.