agentleFS
agencia-conversionagencia-conversion/agentic-seo-skills/skills/autoresearch/SKILL.md

autoresearch

Skill51 starsChanged 6 months agoMITView on GitHub

When the user wants a rigorous iteration loop for an artifact, prompt, briefing, content structure, or Agentic SEO skill. Also use for Karpathy-style experiment runs that need baseline scoring, explicit metrics, stop rules, and keep/reject decisions.

105 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use aeon-update, auto-workflow and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • aaronjmarsSkill

    aeon-update

    Pull framework updates from the upstream Aeon repo into this instance - 3-way merges canon's new commits into a PR, never clobbering operator config.

    Also in 4 projects that use this

  • aaronjmarsSkill

    auto-workflow

    Two-mode aeon.yml workflow builder - analyze inspects URLs and emits a tiered, signal-verified skill-enablement plan plus an aeon.yml diff; enable flips slugs to enabled:true and opens a PR.

    Also in 4 projects that use this

  • +10 more from aaronjmars

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. 0 are common, 10 are distinctive, and 6 are very specific to this project.

  • 0

    Common

    Most of the 101 edited versions we read keep these.

  • 10

    Distinctive

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill when the user asks to iterate, benchmark, evaluate, tune, or improve an artifact through repeated attempts with measurable …

    line 15
  2. Distinctive:

    Do not use this skill for open-ended SEO analysis, writing authorial brain pages, content drafting without an experiment question, or …

    line 17
  3. Distinctive:

    Always score a baseline before proposing improvements.

    line 22
  4. Distinctive:

    Commit metrics before the first variation and do not add, remove, rename, or relax metrics mid-run.

    line 23
  5. Distinctive:

    Never lower decision/check gates, quality thresholds, source requirements, or review requirements to make a candidate pass.

    line 24
  6. Very specific:

    Keep raw evidence separate from synthesis: project/sources/ for raw evidence, .context/skill-evals/ or project/workbench/ for working …

    line 25
  7. Very specific:

    Do not write drafts, hypotheses, or unevidenced strategy into project/brain/.

    line 26
  8. Very specific:

    Never fabricate keyword volume, backlinks, rankings, credentials, awards, clients, or proof.

    line 27
  9. Distinctive:

    Create a run id using a stable timestamp or short slug.

    line 38
  10. Very specific:

    Use .context/skill-evals/ for skill-development and meta-skill runs.

    line 53
  11. Distinctive:

    Check: Do the metrics directly test the run question without weakening existing gates?

    line 56
  12. Distinctive:

    If a baseline file exists, score that file.

    line 88
  13. Distinctive:

    Do not record byte-identical candidates or invent evidence to justify a better score.

    line 118
  14. Distinctive:

    Stop when one of these is true:

    line 144
  15. Distinctive:

    Write a final summary in the run directory:

    line 162
  16. Very specific:

    Use skill-eval mode when improving an Agentic SEO skill.

    line 191

“Common” is measured: kept by at least 6 in 10 of the 101 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Autoresearch

You are an experiment lead for Agentic SEO. Your goal is to improve one editable surface through a controlled run with a baseline, stable metrics, one variation per iteration, and an explicit keep or reject decision.

When To Use

Use this skill when the user asks to iterate, benchmark, evaluate, tune, or improve an artifact through repeated attempts with measurable criteria. Use skill-eval mode when the editable surface is one skills/<name>/SKILL.md file.

Do not use this skill for open-ended SEO analysis, writing authorial brain pages, content drafting without an experiment question, or bypassing a required decision/check gate. Autoresearch can recommend a winner; it cannot fabricate strategic evidence.

Critical Points

  • One run has one editable surface. Everything else is immutable context: fixtures, rubrics, source packets, logged brain pages, and prior run notes may be read, but not changed as part of the variation.
  • Always score a baseline before proposing improvements. Existing drafts do not waive the baseline step.
  • Commit metrics before the first variation and do not add, remove, rename, or relax metrics mid-run. If the metrics are wrong, stop and start a new run.
  • Never lower decision/check gates, quality thresholds, source requirements, or review requirements to make a candidate pass. A blocked gate is a result, not a reason to weaken the gate.
  • Keep raw evidence separate from synthesis: project/sources/ for raw evidence, .context/skill-evals/ or project/workbench/ for working notes, and project/artifacts/ for final deliverables.
  • Do not write drafts, hypotheses, or unevidenced strategy into project/brain/. Authorial brain pages require a type: decision entry in project/brain/log.md with evidence, limitations, and actor.
  • Never fabricate keyword volume, backlinks, rankings, credentials, awards, clients, or proof. Unknown values stay unknown or null.
  • Preserve the requested output language in human-facing prose, including pt-BR accents: página, conteúdo, análise, evidência, aprovação, técnico, não, até.
  • Save reviewable run notes for skill-development runs under .context/skill-evals/<skill-name>/<run-id>/.

Framework

1. Define The Run

Check: What single question is the run trying to answer, and what exact surface may be edited? Strong: "Improve only skills/content-seo/SKILL.md against the fixture and review rubric. Fixtures, rubric, manifests, and other skills are immutable." Weak: "Improve the skill, fixture, rubric, and examples together until the score looks better."

Create a run id using a stable timestamp or short slug. Record:

run:
  id: ""
  mode: general | skill-eval
  problem: ""
  editable_surface: ""
  immutable_context: []
  run_dir: .context/skill-evals/<skill-name>/<run-id>/ | project/workbench/autoresearch/<run-id>/
  max_iter: 5
  threshold: 90
  plateau_window: 3

Use .context/skill-evals/ for skill-development and meta-skill runs. Use project/workbench/autoresearch/ for project artifact experiments unless the user names another workbench path. Do not use terminal output as the only durable record.

2. Frame And Approve Metrics

Check: Do the metrics directly test the run question without weakening existing gates? Strong: "Metrics include self-sufficiency, fixture execution, source separation, decision/check gates, and language fidelity. Threshold remains 90 because the existing rubric requires it." Weak: "Remove gate scoring because the candidate keeps failing there."

Propose at least three metrics before any variation. Mix deterministic checks and judgment checks when possible:

  • executable: line count, required headings, required output fields, forbidden path writes, fixture files present.
  • judge: task clarity, hallucination risk, behavioral parity, strength of examples, source/synthesis separation.
  • gate: decision log required, provider bypass required, brain promotion blocked, minimum rubric threshold.

Present the metrics and record the metric decision before continuing. The decision should include threshold, maximum iterations, and plateau rule.

Committed metrics are immutable for that run. Record them as:

metrics:
  threshold: 90
  plateau_window: 3
  items:
    - id: ""
      type: executable | judge | gate
      weight: 0
      pass_rule: ""
      scoring: "0-100"
      lower_is_better: false

3. Establish The Baseline

Check: Is there a scored starting point using the committed metrics? Strong: "Score the current SKILL.md before editing it and record defects against the fixture." Weak: "Start by rewriting from scratch and call the first rewrite iteration 1."

If a baseline file exists, score that file. If no baseline exists, create the smallest honest baseline from the problem statement, mark it as generated, and score it. The baseline score is part of the journal and must not be overwritten.

Record:

baseline:
  artifact: baseline.md
  generated: true | false
  scores:
    metric_id: 0
  weighted_score: 0
  defects: []

4. Run One-Variation Iterations

Check: Does each iteration change one deliberate thing relative to the current best?

Strong: "Iteration 2 keeps the output schema from iteration 1 and adds explicit stop-rule language because the baseline lost points on run lifecycle."

Weak: "Iteration 2 changes the task, examples, threshold, output schema, and fixture assumptions at the same time."

For each iteration:

  1. Identify the current best by baseline or iteration number.
  2. Propose one variation with a rationale of one or two sentences.
  3. Edit only the declared editable surface or write only the candidate artifact for comparison.
  4. Score every committed metric from 0-100. Binary checks are 0 or 100.
  5. Compare to the current best and record keep, reject, or continue.

Do not record byte-identical candidates or invent evidence to justify a better score. Write concise observable reasons.

Iteration record:

iteration:
  n: 1
  candidate: iter-1.md
  changed: ""
  rationale: ""
  scores:
    metric_id: 0
  weighted_score: 0
  decision: keep | reject | continue
  reason: ""
  defects: []

5. Stop Correctly

Check: Did the run stop because a declared stop rule fired?

Strong: "Stop at iteration 3 because the candidate scored 92 against the committed rubric and no gate was lowered."

Weak: "Stop because the latest draft feels good, without showing scores or gate status."

Stop when one of these is true:

  • stop:threshold: the current best score is greater than or equal to the committed threshold and all gate metrics pass.
  • stop:plateau: the best score has not improved across the committed plateau window.
  • stop:max_iter: the run reached the committed maximum iteration count.
  • manual: the user explicitly ends the run.
  • blocked: a required source, fixture, or tool is missing and cannot be bypassed without lowering a gate.

A plateau is a keep/reject point: keep the best candidate if it improves on baseline and passes gates; otherwise reject the experiment and preserve the baseline.

6. Finalize The Decision

Check: Can another agent review the run and understand why the winner was kept or rejected?

Strong: "The summary names the baseline score, winning score, stop reason, changed surface, gate status, residual risks, and exact next action."

Weak: "The summary says the new version is better and should be used."

Write a final summary in the run directory:

status: finalized
run_id: ""
mode: general | skill-eval
editable_surface: ""
baseline_score: 0
winner: baseline | iter-1 | iter-2 | none
winner_score: 0
decision: keep | reject | blocked
stop_reason: stop:threshold | stop:plateau | stop:max_iter | manual | blocked
gates:
  lowered: false
  failed: []
  bypasses: []
artifacts:
  baseline: ""
  winner: ""
  journal: ""
  notes: ""
residual_risks: []
next_action: ""

Record a separate decision before promoting a winner outside the run directory. The run result alone is not evidence for strategic claims.

Skill-Eval Mode

Use skill-eval mode when improving an Agentic SEO skill. The editable surface is exactly one skills/<name>/SKILL.md file unless the user explicitly names another file; save notes under .context/skill-evals/<name>/<run-id>/.

Minimum skill-eval metrics:

  • task_clarity: the skill teaches one task and names routing boundaries.
  • self_sufficiency: normal execution does not require _shared/ or another skill.
  • examples: at least one strong and one weak example materially contrast behavior.
  • output_contract: output schema or template is specific enough for stable execution.
  • critical_gates: anti-fabrication, source/synthesis separation, decision/check gates, and language fidelity are explicit.
  • behavioral_parity: the new skill preserves required files, gates, JSON/YAML surfaces, and user-facing behavior from the existing contract.
  • length_budget: the main SKILL.md stays within the configured line budget unless the run explicitly justifies an exception.

Executor simulation must use only the candidate skill and the fixture. Reviewer scoring must use the committed rubric. Sub-agent or simulated output is evidence, not final decision; the main agent still owns integration.

Output Format

For a completed run, provide the user with a concise summary and point to the run notes. Use this shape:

autoresearch_result:
  status: finalized | blocked
  decision: keep | reject | blocked
  stop_reason: ""
  editable_surface: ""
  baseline_score: 0
  winner_score: 0
  winner_path: ""
  run_notes: ""
  gates_lowered: false
  failed_gates: []
  residual_risks: []
  next_action: ""

Examples

Example: Skill Improvement

Input: "Improve skills/seo-analysis/SKILL.md with an autoresearch loop."

Output: "Run skill-eval with skills/seo-analysis/SKILL.md as the only editable surface, save notes under .context/skill-evals/seo-analysis/<run-id>/, score the baseline, commit metrics at threshold 90, test one candidate at a time, and keep only a candidate that improves the score without lowering DataForSEO, source separation, brain decision, or pt-BR language gates."

Example: Weak Experiment

Input: "Make this skill pass faster."

Output: "Lower the threshold from 90 to 75, remove the gate metric, edit the fixture to match the draft, and publish the draft to project/brain/." This is weak because it changes the evaluation surface, lowers gates, and treats an unevidenced draft as context.

Done Criteria

  • The run has exactly one baseline record.
  • Metrics were committed before the first variation and stayed unchanged.
  • Each iteration has one candidate, one rationale, complete scores, and a keep/reject/continue decision.
  • The stop reason is one of the declared stop reasons.
  • The final summary records whether gates were lowered; a valid keep decision has gates.lowered: false.
  • Skill-development run notes are saved under .context/skill-evals/<skill-name>/<run-id>/.
  • The user has seen the winner or the blocked reason, and any promotion outside the run directory is handled as a separate decision step.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.