@asermax/pi-tentacles 0.1.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asermax/pi-tentacles",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Spawn, steer, question and collect remote coding agents that run in tentacles.",
   "type": "module",
   "license": "MIT",

package/skills/tentacles/SKILL.md

@@ -16,10 +16,28 @@ A remote agent only keeps what it commits and pushes. Its workspace is disposabl
 
 ## Spawn
 
-`spawn` takes a name, the first prompt and the session's settings. The name shows in your status line, so name it after the agent's task. The settings you leave out come from the plugin's defaults.
+`spawn` takes a name, the first prompt, the session's settings and, optionally, skills, agent definitions and context files (see Skills and agents, and Context files). The name shows in your status line, so name it after the agent's task. The settings you leave out come from the plugin's defaults.
 
 Write the first prompt for someone who has not seen this conversation: the goal, the repository, the branch to push, and what done looks like. Name the repository in the settings when the agent has to work in it, so tentacles clones the repository and, before the agent asks you anything, checks it for work that is not pushed.
 
+## Skills and agents
+
+`spawn` takes `skills`, the paths of skill folders on your machine, each holding a `SKILL.md`, and `agents`, the paths of agent definition files. The remote agent sees each skill and agent by name and description, loads a skill when a task matches it, and starts subagents from its agent definitions by name. A prompt can name a skill as `/skill:<name>` or `/<name>` on its own, with a space or the start or end of the prompt on each side, and the remote agent reads that skill's instructions before acting on it.
+
+Skills and agents are fixed at spawn. Include everything the job needs, and spawn a new remote agent when the job needs a different set.
+
+Every definition is checked on your machine before anything is sent. When any fails, `spawn` creates nothing and returns every problem with its path, the skills' problems in one group and the agents' in another. Fix them all, then spawn again. An agent definition's frontmatter `name` has to equal its file name without `.md`.
+
+A remote agent works on its own, so a skill that would stop to ask the person has nobody to ask. Write the handoff so the remote agent decides wherever a skill would stop for the user, ignores any instruction in a skill to ask the user, and lists every such decision in its final report. For a stop point it cannot decide, such as a credential it lacks, say in the handoff what to do, which can be asking you with its question tool.
+
+## Context files
+
+`spawn` takes `context`, the paths of files and folders on your machine that the job needs and the repository does not hold, such as a change's scratch files. Each path lands in the remote agent's `/context` folder under its own name: a file at `/context/<file name>`, a folder at `/context/<folder name>/…`. `/context` is outside the repository, so the files never reach its commits. A folder takes everything under it, a symlink is sent as the file or folder it points to, and every file keeps its permission bits.
+
+The remote agent has a copy that is fixed at spawn. Its edits to the copy are lost when its workspace restarts and never come back to you, so spawn a new remote agent when the job needs different files. The remote agent is told only that you sent files and that they are in `/context`, so say in the handoff what the files are and how to use them.
+
+The paths are checked on your machine before anything is sent. A path that does not exist or cannot be read, two paths with the same name, or files that pack over 5 MB make `spawn` create nothing and return every problem with its path in a Context group, beside the Skills and Agents groups.
+
 ## Being woken
 
 You are woken when a remote agent stops. The wake carries the agent's last message when it finishes, the reason when it fails, and the question when it asks one. You never poll. If you think a wake was missed, run `list`.
@@ -42,4 +60,4 @@ Close a remote agent once you have its result. Closing aborts what it is doing a
 
 ## Listing remote agents
 
-`list` returns every remote agent you started from this session, closed ones included, with its status. A forked session starts with none.
+`list` returns every remote agent you started from this session, closed ones included, with its status, its settings and the names of its skills and agents. A forked session starts with none.