From 66723f8bc0d98cec26a02a562ee56fcdb1419036 Mon Sep 17 00:00:00 2001
From: evalstate <1936278+evalstate@users.noreply.github.com>
Date: Wed, 27 Aug 2025 19:03:42 +0100
Subject: [PATCH 1/3] enable use of AGENTS.md as an alternative to PROMPTS.md

---
 packages/tiny-agents/README.md                |  4 +-
 .../tiny-agents/src/lib/loadConfigFrom.ts     | 38 +++++++++++--------
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/packages/tiny-agents/README.md b/packages/tiny-agents/README.md
index df60201c23..12eb6fcfc8 100644
--- a/packages/tiny-agents/README.md
+++ b/packages/tiny-agents/README.md
@@ -73,7 +73,7 @@ Or using a local or remote endpoint URL:
 
 Where `servers` is a list of MCP servers (we support Stdio, SSE, and HTTP servers).
 
-Optionally, you can add a `PROMPT.md` file to override the default Agent prompt.
+Optionally, you can add a `PROMPT.md` or [`AGENTS.md`](https://agents.md/) file to override the default Agent prompt.
 
 Then just point tiny-agents to your local folder:
 
@@ -93,7 +93,7 @@ npx @huggingface/tiny-agents run "julien-c/flux-schnell-generator"
 ```
 
 > [!NOTE]
-> Want to share your own agent with the community? Submit a PR to the [Tiny Agents](https://huggingface.co/datasets/tiny-agents/tiny-agents/discussions) repository on the Hub. Your submission must include an `agent.json` file, and you can optionally add a `PROMPT.md` file. To help others understand your agent's capabilities, consider including an `EXAMPLES.md` file with sample prompts and use cases.
+> Want to share your own agent with the community? Submit a PR to the [Tiny Agents](https://huggingface.co/datasets/tiny-agents/tiny-agents/discussions) repository on the Hub. Your submission must include an `agent.json` file, and you can optionally add a `PROMPT.md` or [`AGENTS.md`](https://agents.md/) file. To help others understand your agent's capabilities, consider including an `EXAMPLES.md` file with sample prompts and use cases.
 
 ## Advanced: Programmatic Usage
 
diff --git a/packages/tiny-agents/src/lib/loadConfigFrom.ts b/packages/tiny-agents/src/lib/loadConfigFrom.ts
index 7396f110df..e8c8ec2745 100644
--- a/packages/tiny-agents/src/lib/loadConfigFrom.ts
+++ b/packages/tiny-agents/src/lib/loadConfigFrom.ts
@@ -6,7 +6,7 @@ import type { TinyAgentConfig } from "./types";
 import { debug, error } from "./utils";
 
 const FILENAME_CONFIG = "agent.json";
-const FILENAME_PROMPT = "PROMPT.md";
+const PROMPT_FILENAMES = ["PROMPT.md", "AGENTS.md"] as const;
 
 const TINY_AGENTS_HUB_REPO: RepoDesignation = {
 	name: "tiny-agents/tiny-agents",
@@ -29,10 +29,13 @@ async function tryLoadFromDirectory(dirPath: string): Promise<TinyAgentConfig |
 	}
 
 	let prompt: string | undefined;
-	try {
-		prompt = await readFile(join(dirPath, FILENAME_PROMPT), { encoding: "utf8" });
-	} catch {
-		debug(`PROMPT.md not found in ${dirPath}, continuing without prompt template`);
+	for (const filename of PROMPT_FILENAMES) {
+		try {
+			prompt = await readFile(join(dirPath, filename), { encoding: "utf8" });
+			break;
+		} catch {
+			debug(`${filename} not found in ${dirPath}, continuing without prompt template`);
+		}
 	}
 
 	try {
@@ -60,17 +63,20 @@ async function tryLoadFromHub(agentId: string): Promise<TinyAgentConfig | undefi
 	}
 
 	let prompt: string | undefined;
-	try {
-		const promptPath = await downloadFileToCacheDir({
-			repo: TINY_AGENTS_HUB_REPO,
-			path: `${agentId}/${FILENAME_PROMPT}`,
-			accessToken: process.env.HF_TOKEN,
-		});
-		prompt = await readFile(promptPath, { encoding: "utf8" });
-	} catch {
-		debug(
-			`PROMPT.md not found in https://huggingface.co/datasets/tiny-agents/tiny-agents/tree/main/${agentId}, continuing without prompt template`
-		);
+	for (const filename of PROMPT_FILENAMES) {
+		try {
+			const promptPath = await downloadFileToCacheDir({
+				repo: TINY_AGENTS_HUB_REPO,
+				path: `${agentId}/${filename}`,
+				accessToken: process.env.HF_TOKEN,
+			});
+			prompt = await readFile(promptPath, { encoding: "utf8" });
+			break;
+		} catch {
+			debug(
+				`${filename} not found in https://huggingface.co/datasets/tiny-agents/tiny-agents/tree/main/${agentId}, continuing without prompt template`
+			);
+		}
 	}
 
 	return {

From 11028da8399434cf0a7dc373e448a07dc5f95c92 Mon Sep 17 00:00:00 2001
From: evalstate <1936278+evalstate@users.noreply.github.com>
Date: Fri, 29 Aug 2025 16:30:57 +0100
Subject: [PATCH 2/3] improve debug output when prompt file is not found

---
 packages/tiny-agents/src/lib/loadConfigFrom.ts | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/packages/tiny-agents/src/lib/loadConfigFrom.ts b/packages/tiny-agents/src/lib/loadConfigFrom.ts
index e8c8ec2745..c6190de5b4 100644
--- a/packages/tiny-agents/src/lib/loadConfigFrom.ts
+++ b/packages/tiny-agents/src/lib/loadConfigFrom.ts
@@ -34,9 +34,14 @@ async function tryLoadFromDirectory(dirPath: string): Promise<TinyAgentConfig |
 			prompt = await readFile(join(dirPath, filename), { encoding: "utf8" });
 			break;
 		} catch {
-			debug(`${filename} not found in ${dirPath}, continuing without prompt template`);
+			/* empty */
 		}
 	}
+	if (undefined == prompt) {
+		debug(
+			`${PROMPT_FILENAMES.join(", ")} could not be loaded locally from ${dirPath}, continuing without prompt template`
+		);
+	}
 
 	try {
 		return {
@@ -73,11 +78,16 @@ async function tryLoadFromHub(agentId: string): Promise<TinyAgentConfig | undefi
 			prompt = await readFile(promptPath, { encoding: "utf8" });
 			break;
 		} catch {
-			debug(
-				`${filename} not found in https://huggingface.co/datasets/tiny-agents/tiny-agents/tree/main/${agentId}, continuing without prompt template`
-			);
+			/* empty */
 		}
 	}
+	if (undefined == prompt) {
+		debug(
+			`${PROMPT_FILENAMES.join(
+				", "
+			)}  not found in https://huggingface.co/datasets/tiny-agents/tiny-agents/tree/main/${agentId}, continuing without prompt template`
+		);
+	}
 
 	return {
 		configJson,

From f152946d91370ef9cbef10f6ec25b52dc73bfe20 Mon Sep 17 00:00:00 2001
From: evalstate <1936278+evalstate@users.noreply.github.com>
Date: Fri, 29 Aug 2025 16:44:07 +0100
Subject: [PATCH 3/3] reorder preference of AGENTS > PROMPT

---
 packages/tiny-agents/README.md                 | 2 +-
 packages/tiny-agents/src/lib/loadConfigFrom.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/tiny-agents/README.md b/packages/tiny-agents/README.md
index 12eb6fcfc8..6d50e9a008 100644
--- a/packages/tiny-agents/README.md
+++ b/packages/tiny-agents/README.md
@@ -73,7 +73,7 @@ Or using a local or remote endpoint URL:
 
 Where `servers` is a list of MCP servers (we support Stdio, SSE, and HTTP servers).
 
-Optionally, you can add a `PROMPT.md` or [`AGENTS.md`](https://agents.md/) file to override the default Agent prompt.
+Optionally, you can add an [`AGENTS.md`](https://agents.md/) (or `PROMPT.md`) file to override the default Agent prompt.
 
 Then just point tiny-agents to your local folder:
 
diff --git a/packages/tiny-agents/src/lib/loadConfigFrom.ts b/packages/tiny-agents/src/lib/loadConfigFrom.ts
index c6190de5b4..365c7444af 100644
--- a/packages/tiny-agents/src/lib/loadConfigFrom.ts
+++ b/packages/tiny-agents/src/lib/loadConfigFrom.ts
@@ -6,7 +6,7 @@ import type { TinyAgentConfig } from "./types";
 import { debug, error } from "./utils";
 
 const FILENAME_CONFIG = "agent.json";
-const PROMPT_FILENAMES = ["PROMPT.md", "AGENTS.md"] as const;
+const PROMPT_FILENAMES = ["AGENTS.md", "PROMPT.md"] as const;
 
 const TINY_AGENTS_HUB_REPO: RepoDesignation = {
 	name: "tiny-agents/tiny-agents",