Folder contract
What belongs in the source workspace and how the agent treats each file.
The folder contract defines what the agent may treat as evidence, what it should ignore, and where generated files belong. A clear boundary makes the manuscript easier to audit.
One project, one folder#
Use one dedicated top-level folder per manuscript. The agent reads recursively, so nested folders are useful for grouping but do not hide content.
coastal-risk-manuscript/
One research question, one evidence set.
Desktop/
Unrelated files, secrets, and ambiguous scope.
Recommended structure#
The skill does not require a rigid schema, but predictable names make intent clear and reduce follow-up questions.
my-research/
├── README.md
├── notes/
│ ├── research-question.md
│ └── methods-notes.docx
├── data/
│ ├── results.xlsx
│ └── analysis.csv
├── figures/
│ ├── figure-01.png
│ └── figure-02.pdf
├── sources/
│ ├── interviews.pdf
│ └── prior-draft.docx
├── references.bib
└── journal-template/ # optionalA root README.md is the best place to state the research question, describe terminology, flag the newest dataset, and explain any files that must take priority.
Supported material#
| Material | Typical files | How it is used |
|---|---|---|
| Research notes | .md .txt .docx .pdf | Questions, rationale, methods, interpretation |
| Data & results | .csv .tsv .xlsx | Reported values, tables, and traceable summaries |
| Figures | .png .jpg .pdf | Article figures and visual evidence |
| References | .bib .ris .pdf | Citations and bibliography records |
| Code outputs | .json .html .log | Reproducibility context and computed results |
| Journal files | .cls .sty .bst .tex | Template rules in specific-template mode |
What to keep out#
- Passwords, access tokens, private keys, and credentials.
- Personally identifying raw data that is not cleared for manuscript use.
- Unrelated projects or duplicate archives with unclear authority.
- Generated output from an earlier run unless it is intentionally being revised.
- Paywalled or licensed material you are not permitted to process.
Evidence source of truth#
Files in the workspace are evidence candidates, not automatic truth. The agent should distinguish raw observations, analysis outputs, interpretations, and author instructions.