Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions .agents/skills/aeo_brief/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,16 @@ Use the Peec MCP when available. Prefer source data over invented SEO advice.

Keep Peec output compact. The brief should explain what the data suggests, not reproduce a full report.

For each content recommendation:

* Record the exact query or recommendation and what the data measured.
* Say whether the data supports that specific topic or only a broader topic. A query about software testing, for example, does not by itself show demand for every testing tool.
* If you recommend a narrower topic without direct supporting data, label it as your editorial recommendation rather than measured demand.
* If no matching query was found, say that; do not claim it proves there is no demand.
* Keep the recommendation within the page's agreed purpose. Do not add unrelated topics or unsupported product promises to include more search terms.

See [SEO data in AGENTS.md](../../../AGENTS.md#seo-data) for the shared rules.

## Repo research workflow

Ground every recommendation in the current docs:
Expand Down
88 changes: 88 additions & 0 deletions .agents/skills/doc_quality_policy/test_editorial_guidance.py
Original file line number Diff line number Diff line change
@@ -1,15 +1,30 @@
"""Objective guidance invariants; prose quality is evaluated separately."""
import importlib.util
import re
import unittest
from pathlib import Path

ROOT = Path(__file__).resolve().parents[3]
LINK_CHECKER_SPEC = importlib.util.spec_from_file_location(
"check_links", ROOT / ".agents/skills/check_for_broken_links/check_links.py")
check_links = importlib.util.module_from_spec(LINK_CHECKER_SPEC)
LINK_CHECKER_SPEC.loader.exec_module(check_links)


class EditorialGuidanceTests(unittest.TestCase):
def text(self, path):
return (ROOT / path).read_text()

def assert_agents_links(self, path, text):
links = re.findall(r"\]\(([^)]+AGENTS\.md)#([^)]+)\)", text)
self.assertIn("check-connected-procedures", [anchor for _, anchor in links],
f"{path}: missing #check-connected-procedures link")
checker = check_links.LinkChecker(ROOT)
for target, anchor in links:
self.assertEqual((path.parent / target).resolve(), ROOT / "AGENTS.md")
valid, error, _ = checker.check_fragment(f"{target}#{anchor}", path)
self.assertTrue(valid, error)

def test_canonical_reader_test_is_referenced(self):
agents = self.text("AGENTS.md")
self.assertEqual(agents.count("#### Reader-understanding test"), 1)
Expand Down Expand Up @@ -72,6 +87,79 @@ def test_quickstart_timing_can_be_omitted_when_unverified(self):
".agents/templates/quickstart.md"):
self.assertIn("omit it when unverified", self.text(path))

def test_connected_procedure_checks_have_one_canonical_home(self):
agents = self.text("AGENTS.md")
self.assertEqual(agents.count("#### Check connected procedures"), 1)
section = agents.split("#### Check connected procedures\n", 1)[1].split("\n### ", 1)[0]
for check in ("Starting work", "Overlapping rules", "Existing exclusions",
"Unmatched inputs", "Work already in progress",
"Passing work to the next stage", "Tests"):
self.assertIn(f"* **{check}** -", section)
for skill in ("draft_docs", "review-docs-pr"):
path = ROOT / f".agents/skills/{skill}/SKILL.md"
self.assert_agents_links(path, path.read_text())

def test_other_valid_agents_heading_links_are_allowed(self):
for skill in ("draft_docs", "review-docs-pr"):
with self.subTest(skill=skill):
path = ROOT / f".agents/skills/{skill}/SKILL.md"
text = path.read_text() + (
"\n[Reader-understanding test]"
"(../../../AGENTS.md#reader-understanding-test)\n")
self.assert_agents_links(path, text)

def test_missing_connected_procedures_link_is_rejected(self):
for skill in ("draft_docs", "review-docs-pr"):
with self.subTest(skill=skill):
path = ROOT / f".agents/skills/{skill}/SKILL.md"
text = path.read_text().replace(
"AGENTS.md#check-connected-procedures", "AGENTS.md#procedural")
with self.assertRaisesRegex(AssertionError, "check-connected-procedures"):
self.assert_agents_links(path, text)

def test_nonexistent_agents_heading_link_is_rejected(self):
for skill in ("draft_docs", "review-docs-pr"):
with self.subTest(skill=skill):
path = ROOT / f".agents/skills/{skill}/SKILL.md"
text = path.read_text() + (
"\n[Missing section](../../../AGENTS.md#missing-guidance-heading)\n")
with self.assertRaisesRegex(AssertionError, "missing-guidance-heading"):
self.assert_agents_links(path, text)

def test_setup_jobs_are_listed_separately(self):
agents = self.text("AGENTS.md")
section = agents.split("**Separate setup, instructions, and testing.**", 1)[1]
section = section.split("\n- **", 1)[0]
for job in ("Configuration", "Access", "Instructions", "Testing"):
self.assertIn(f" - **{job}** -", section)
self.assertIn("State instructions explicitly", agents)
self.assertIn("Do not expect readers to infer a required action", agents)

def test_new_guidance_does_not_use_the_compressed_shorthand(self):
paths = ("AGENTS.md", ".agents/skills/draft_docs/SKILL.md",
".agents/skills/review-docs-pr/SKILL.md",
".agents/skills/aeo_brief/SKILL.md",
".agents/templates/procedural.md", ".agents/templates/feature-doc.md")
for path in paths:
text = self.text(path)
for phrase in ("cumulative routing exclusions", "continued-conversation ownership",
"existing-agent paths", "umbrella signal", "When examples compose"):
self.assertNotIn(phrase, text, path)

def test_setup_template_hints_state_actions_and_remain_bracketed(self):
for template in ("procedural", "feature-doc"):
text = self.text(f".agents/templates/{template}.md")
self.assertNotIn("<!--", text)
hints = [line for line in text.splitlines() if line.startswith("[")]
for instruction in ("State what the reader is configuring",
"If readers can reuse an agent or resource",
"Give configuration choices",
"If this procedure connects to another",
"Preserve existing filters and exclusions",
"Verify whether configuration changes affect"):
self.assertTrue(any(instruction in hint and hint.endswith("]")
for hint in hints), (template, instruction))


if __name__ == "__main__":
unittest.main()
22 changes: 22 additions & 0 deletions .agents/skills/draft_docs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,28 @@ Create the documentation using the appropriate template from `.agents/templates/

During the deletion pass, apply AGENTS.md → Procedural → Reader-understanding test. A concept explained elsewhere may still be necessary beside a step for a direct-arrival reader. Omit optional scaffold sections rather than filling them with repetition.

For each setup procedure:

* State what the reader is configuring before listing fields or example names. For example, say "Create an automation that checks broken links" before giving the automation's name.
* Explain what each selected agent, environment, or credential is used for. Give the field, command, or file to change and the value to use.
* Show how to edit or select an existing agent or resource when the task supports reuse. For file-based setup, identify the existing file or agent directory instead of assuming the example name matches every factory.
* Separate configuration choices, tool and credential access, skill or prompt instructions, and test execution into distinct steps or groups of related steps. Do not imply that writing a skill installs tools or grants access.
* Put safety limits beside the action they restrict and inside any prompt that readers can copy separately.
* Explain the sample test input. Require test credentials only if that test needs authentication. Apply configuration changes before testing, and name the behavior and evidence to check; do not treat a completed run as proof.
* After editing a sentence, reread the whole paragraph and the surrounding steps. Check that the purpose is still clear, references are unambiguous, and actions remain in the correct order.

When readers can combine this procedure with another:

* Identify which event starts each task and which agent receives it.
* Check whether one input can match several rules. Say whether that is intended. If only one rule should act, give conditions that prevent the other rules from matching.
* Preserve existing filters and exclusions when adding new ones. Do not replace an existing exclusion list with only the new value.
* Explain what happens to inputs that match none of the specialized rules.
* Verify whether the changes affect new tasks, existing conversations, or both. Do not claim that changing a rule transfers work to another agent without verifying that behavior.
* State what passes to the next stage, what result it returns, where it stops, and which decisions require human approval.
* Test matching, overlapping, and unmatched inputs, plus an existing conversation when continuation is supported. Give the expected result for each case and record tests that could not be run.

These checks follow [Order from intent to technical detail](../../../AGENTS.md#order-from-intent-to-technical-detail), [Procedural](../../../AGENTS.md#procedural), and [Check connected procedures](../../../AGENTS.md#check-connected-procedures) in `AGENTS.md`.

Record an editorial verdict in the PR rationale: reader task, concept ownership across siblings, repetition and unnecessary scaffolds removed, unsupported assurances corrected, and useful understanding preserved. Link or relocate necessary facts rather than deleting them for length. Removing a page or changing its purpose requires human approval; identify each unsupported claim and its narrow correction instead.

### 8. Run style lint and the compression contract check
Expand Down
Loading
Loading