\r \r

pyscripts-org – Organizing & maintaining Python scripts for agents\r

\r

1. Every script MUST have a summary block at the END of the file\r

\r Place it after all the code, as the very last lines of the file. \r Required structure:\r \r

# ===== SUMMARY =====\r
# Brief description of what the script does and when to use it.\r
# Syntax: python script.py \x3Cargs>\r
# ===== END SUMMARY =====\r
```\r
\r
**Reason:** LLMs/agents pay the most attention to the end of the text; placing the summary there ensures the most up-to-date information is captured when generating docs.\r
\r
## 2. Automatic and manual documentation files\r
\r
### 2.1 `pyscripts_docs.md` – generated automatically by `summary.py`\r
\r
This is the index of all scripts, containing a table:\r
\r
| Script | Summary | Syntax |\r
|--------|---------|--------|\r
| … | … | … |\r
\r
The script `summary.py` scans all `.py` files, reads the `# ===== SUMMARY =====` block at the end of each file, extracts the description and syntax, then writes `pyscripts_docs.md`.\r
\r
### 2.2 `pyscripts_pitfall.md` – manually recorded errors\r
\r
Whenever an agent runs a script and encounters an error, it will:\r
1. Read the script’s code to understand the cause.\r
2. Fix the error (if needed).\r
3. Record the error description and resolution into `pyscripts_pitfall.md` using this template:\r
\r
```markdown\r
### Error: [script name] – [short description]\r
- Cause: ...\r
- Fix: ...\r
- Date encountered: ...\r
```\r
\r
This file helps avoid repeating mistakes and speeds up future handling.\r
\r
## 3. Workflow with scripts\r
\r
1. **Want to do something** → open `pyscripts_docs.md`.\r
2. **Look for a suitable script:**\r
   - If it exists → run the script with `python \x3Cscript.py> \x3Cargs>` (or via terminal tool).\r
   - If not → check if a similar script exists, modify it to fit (update its summary), or create a new script with a summary block at the end.\r
3. **Run the script:**\r
   - If successful → done.\r
   - If an error occurs → **read the script's code** to understand the error.\r
4. **After fixing the error** → update the code and summary (if behavior changed).\r
5. **Record in `pyscripts_pitfall.md`** if the error is worth remembering, to prevent it in the future.\r
6. **Run `summary.py`** every time a script is added/modified/deleted to update `pyscripts_docs.md`.\r
\r
## 4. No forced `execute_code` – script files remain primary\r
\r
Even small scripts are saved as standalone `.py` files for easy reuse.  \r
`execute_code` is only used for one-liners or quick checks.\r
\r
## 5. Core scripts\r
\r
| Script | Function |\r
|--------|-----------|\r
| `summary.py` | Scans all `.py` files, extracts end-of-file summaries, generates `pyscripts_docs.md` |\r
\r
Other utility scripts (query, update, fix…) will be listed in `pyscripts_docs.md`.\r
\r
---\r
\r
**Summary of key changes:**\r
- Skill name: **`pyscripts-org`**.\r
- Index: **`pyscripts_docs.md`** (auto-generated).\r
- Added **`pyscripts_pitfall.md`** (manual error log).\r
- Clear workflow: **look up → run → error → read code → record pitfall → update docs**.\r
- Summary block stays at end of file; no periodic cleanup.