agentleFS
kayspiegelkayspiegel/survey-insight-skills/AGENTS.md

survey-insight-skills

AGENTS.md2 starsChanged 3 months agoMITView on GitHub

Workspace for analyzing quantitative survey CSVs with an AI coding agent. Goal: test hypotheses, present results for management, and build decision briefs from research data. There is a shared analysis engine and a set of skills built on top of it. When a request concerns survey data, use the matching skill — do not write ad-hoc analysis code. - Engine: scripts/survey.py (standard library only; profile / freq / text / quality). Run it from the project root. Metadata/timestamp detection is…

The file

We split this AGENTS.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

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

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

    Every skill exists in English and German with identical behavior (see README.md for the full list).

    line 18
  2. Distinctive:

    Check it is still the right context: If the document names a different data set than the file being analyzed, or a fieldwork period that …

    line 49
  3. Very specific:

    Write statistics as plain text (Chi² = 12.094, p = 0.438, Cramér's V = 0.17) — no LaTeX or $…$ math, which many Markdown viewers show raw.

    line 72
  4. Distinctive:

    No personal raw data (ids, timestamps, identifying quotes) in output.

    line 75

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “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
AGENTS.md

Project context

Workspace for analyzing quantitative survey CSVs with an AI coding agent. Goal: test hypotheses, present results for management, and build decision briefs from research data.

Toolkit (use it instead of building your own)

There is a shared analysis engine and a set of skills built on top of it. When a request concerns survey data, use the matching skill — do not write ad-hoc analysis code.

  • Engine: scripts/survey.py (standard library only; profile / freq / text / quality). Run it from the project root. Metadata/timestamp detection is multilingual (English + German).
  • Skills live in .agents/skills/<name>/SKILL.md and follow the open Agent Skills standard, so any skills-capable agent finds them. .claude/skills/ holds symlinks to the same folders for Claude Code. Edit the files under .agents/skills/ — never the symlinks.
  • Every skill exists in English and German with identical behavior (see README.md for the full list). Invoke a skill by name, with your question as the argument; in tools with slash commands that is /<name> <question>:
    • English: survey-report, hypothesis-check, decision-brief, executive-summary, segment-profile, verbatim-themes, data-check, survey-context.
    • German: umfrage-report, hypothese-check, entscheidungsvorlage, management-summary, segment-profil, freitext-themen, daten-check, umfrage-kontext.

Survey context (read it before writing any report)

A data set may come with a context document describing what the CSV cannot state about itself: purpose, subject, recruiting, who is missing, audience, expectations. It is written by survey-context / umfrage-kontext or by hand.

  • Look for it, always. Next to the CSV, named after it: kundenumfrage.csv → kundenumfrage.context.md. If the folder holds exactly one CSV, a plain survey-context.md counts too. If none exists, analyze as before — and mention once, at the end of the reply, that survey-context would put the study design into the report.
  • Use it for framing, never for numbers. It supplies the subject, the glossary, the audience and the study design. Figures still come only from survey.py.
  • Carry the design into the report. The "Who is missing" section and anything from recruiting or the fieldwork circumstances that limits the findings belongs in the method/limitations part of every report — in the report's own words, not as a quote. This is not derivable from the data and is exactly what reports have been missing.
  • Expectations are something to test, never something to support. The expectations section states prior assumptions. Never cite one as evidence, never let it steer which analyses are run or how a finding is worded, never soften a result to fit one. Take one up only where the data actually answer it, and then with an explicit verdict — a report saying "you expected X, the data do not show it" is the most valuable one this toolkit can write.
  • Check it is still the right context. If the document names a different data set than the file being analyzed, or a fieldwork period that does not match the data, do not use it silently — say so and ask once. Context from wave 1 quietly reused in wave 3 is a failure mode of its own.
  • Contradictions between context and data are findings. "You state only active users were surveyed, but 12% report never using the product" belongs in the report, not in the bin. data-check / daten-check look for this on purpose; the other skills report it when they stumble over it.
  • The document can be more sensitive than the CSV (pending decisions, strategy, internal metrics). It is gitignored by default; never copy it wholesale into a report.

Cross-cutting rules (apply to every analysis)

  • All numbers come from survey.py — never estimate from raw data or count "in your head".
  • Percentages always relate to the respondents who answered the given column; for multi-select the sum is > 100% (label it as such).
  • Compute aggregates (top-2-box, "positive overall", any group of categories) from the absolute counts, never by adding up the engine's rounded percentages. 73 of 140 is 52.1%, not 13.6% + 38.6% = 52.2%. Round once, at the end, to one decimal.
  • For group differences, judge significance and effect size together (freq … --sig); correlation is not causation. Pass on the engine's reliability warnings (e.g. expected cell frequency < 5) instead of dropping them.
  • Flag small subgroups (n < ~30) as weakly reliable.
  • Write statistics as plain text (Chi² = 12.094, p = 0.438, Cramér's V = 0.17) — no LaTeX or $…$ math, which many Markdown viewers show raw.
  • Reports as Markdown to reports/ (YYYY-MM-DD_short-title.md), never overwrite.
  • No personal raw data (ids, timestamps, identifying quotes) in output.
  • Output language = language of the question (skills default to English or German accordingly).

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.