From 98d5818b32b767ff826468f15f05b9057189be53 Mon Sep 17 00:00:00 2001 From: Ge Song Date: Fri, 20 Mar 2026 19:02:13 +0800 Subject: [PATCH] docs(bluecraft-agentic-docs): clarify file path reference rules Add explicit guidance to use repository-relative paths in backticks when referencing files from `AGENTS.md` and `agent-docs/`. Prevent machine-local absolute paths and Markdown links in these docs so routing instructions stay portable and consistent. --- skills/bluecraft-agentic-docs/SKILL.md | 2 ++ .../bluecraft-agentic-docs/references/root-agents-template.md | 1 + skills/bluecraft-agentic-docs/references/rule-doc-template.md | 1 + 3 files changed, 4 insertions(+) diff --git a/skills/bluecraft-agentic-docs/SKILL.md b/skills/bluecraft-agentic-docs/SKILL.md index 7347725..4b3c0b5 100644 --- a/skills/bluecraft-agentic-docs/SKILL.md +++ b/skills/bluecraft-agentic-docs/SKILL.md @@ -30,6 +30,8 @@ Do not use this skill for end-user documentation, product manuals, README conten - Rules should be actionable, not slogan-like. - Prefer standard Markdown headings and lists over wrapper tags for structure. - Write for maintainers. State actions, constraints, and decision criteria directly. +- When referencing repository files from `AGENTS.md` or `agent-docs/`, prefer plain repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links. +- Do not embed machine-local absolute filesystem paths such as `/home/...`. - Do not mix general agentic-documentation rules with project-specific business rules, product instructions, media planning, or end-user documentation guidance in the same general-purpose file. - Treat the `AGENTS.md` at the root of the current Git working tree as the primary routing entrypoint. - Keep common, repository-wide constraints in that root `AGENTS.md`. diff --git a/skills/bluecraft-agentic-docs/references/root-agents-template.md b/skills/bluecraft-agentic-docs/references/root-agents-template.md index 3a3846d..fd0e278 100644 --- a/skills/bluecraft-agentic-docs/references/root-agents-template.md +++ b/skills/bluecraft-agentic-docs/references/root-agents-template.md @@ -26,4 +26,5 @@ Use this structure for the `AGENTS.md` at the root of the current Git working tr - Keep this file short. - Treat this file as an instruction document, not a passive index. - Route to child docs only when they are actually needed. +- When routing to child docs, write repository-relative paths in backticks such as `agent-docs/example.md`, not Markdown links or machine-local absolute filesystem paths. - Do not turn the root file into a dump of all topic-specific rules. diff --git a/skills/bluecraft-agentic-docs/references/rule-doc-template.md b/skills/bluecraft-agentic-docs/references/rule-doc-template.md index 74199fb..3c8f6e7 100644 --- a/skills/bluecraft-agentic-docs/references/rule-doc-template.md +++ b/skills/bluecraft-agentic-docs/references/rule-doc-template.md @@ -31,5 +31,6 @@ Use this structure for Markdown files inside `agent-docs/` when the document's m - Make the scope explicit. - Keep the document responsible for one topic. - Use semantic filenames and headings. +- If the document references repository files, write repository-relative paths in backticks, not Markdown links or machine-local absolute filesystem paths. - State the user or maintainer decision directly: what to do, what to avoid, and how to choose. - Prefer linking to inventories, examples, or narrower child docs instead of embedding long registries inline.