clawmini 0.0.7 → 0.0.9

package/templates/environments/cladding/allowlist-domain.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// cwd is guaranteed to sit inside the env's target directory, which is in
+// turn inside the workspace. Walk up looking for .cladding/config, stopping
+// at the workspace root (the dir containing .clawmini) so we never cross
+// into an ancestor project.
+function findCladdingConfigDir(startDir) {
+  let curr = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(curr, '.cladding', 'config');
+    if (fs.existsSync(candidate)) return candidate;
+    if (fs.existsSync(path.join(curr, '.clawmini'))) return null;
+    const parent = path.dirname(curr);
+    if (parent === curr) return null;
+    curr = parent;
+  }
+}
+
+const domains = process.argv.slice(2).filter((arg) => arg.length > 0);
+if (domains.length === 0) {
+  console.error('Usage: allowlist-domain <domain> [<domain>...]');
+  process.exit(1);
+}
+
+const domainPattern = /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
+for (const domain of domains) {
+  if (!domainPattern.test(domain)) {
+    console.error(`Invalid domain: ${domain}`);
+    process.exit(1);
+  }
+}
+
+const configDir = findCladdingConfigDir(process.cwd());
+if (!configDir) {
+  console.error('Could not locate .cladding/config within the workspace.');
+  process.exit(1);
+}
+
+const allowlistPath = path.join(configDir, 'sandbox_domains.lst');
+
+// O_NOFOLLOW on both read and write: a symlink at the allowlist path would
+// otherwise redirect host-privileged writes to an attacker-chosen file.
+function readAllowlist() {
+  let fd;
+  try {
+    fd = fs.openSync(allowlistPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } catch (err) {
+    if (err.code === 'ENOENT') return '';
+    if (err.code === 'ELOOP') {
+      console.error(`Refusing to follow symlink at allowlist path: ${allowlistPath}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    const buf = Buffer.alloc(st.size);
+    fs.readSync(fd, buf, 0, st.size, 0);
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function appendAllowlist(text) {
+  let fd;
+  try {
+    fd = fs.openSync(
+      allowlistPath,
+      fs.constants.O_WRONLY |
+        fs.constants.O_APPEND |
+        fs.constants.O_CREAT |
+        fs.constants.O_NOFOLLOW,
+      0o644
+    );
+  } catch (err) {
+    if (err.code === 'ELOOP') {
+      console.error(`Refusing to follow symlink at allowlist path: ${allowlistPath}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  try {
+    fs.writeSync(fd, text);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const existing = readAllowlist();
+const existingDomains = new Set(
+  existing
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+);
+
+const added = [];
+for (const domain of domains) {
+  if (!existingDomains.has(domain)) {
+    existingDomains.add(domain);
+    added.push(domain);
+  }
+}
+
+if (added.length === 0) {
+  console.log('No new domains to add; allowlist already contains all requested domains.');
+  process.exit(0);
+}
+
+const appendSuffix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+appendAllowlist(`${appendSuffix}${added.join('\n')}\n`);
+console.log(`Added ${added.length} domain(s) to allowlist: ${added.join(', ')}`);
+
+const reload = spawnSync('cladding', ['reload-proxy'], {
+  stdio: 'inherit',
+  cwd: path.dirname(configDir),
+});
+if (reload.status !== 0) {
+  console.error('Warning: `cladding reload-proxy` exited with code', reload.status);
+  process.exit(reload.status ?? 1);
+}

package/templates/environments/cladding/env.json

@@ -3,5 +3,25 @@
   "up": "cladding up",
   "down": "cladding down",
   "prefix": "cladding run {ENV_ARGS} sh -c '{COMMAND}'",
-  "envFormat": "--env {key}"
+  "envFormat": "--env {key}",
+  "exportLiteTo": ".cladding/tools/bin",
+  "baseDir": "/home/user/workspace",
+  "policies": {
+    "allowlist-domain": {
+      "description": "Add one or more domains to the proxy allowlist. Usage: allowlist-domain <domain> [<domain>...]",
+      "command": "./allowlist-domain.mjs",
+      "allowHelp": false
+    },
+    "run-with-network": {
+      "description": "Run a shell command with network access. May require first allowlisting domains. Pass the command via --command, e.g. --command \"npm install\". Supports pipes, &&, env vars, etc.",
+      "allowHelp": true,
+      "command": "./run-with-network.mjs"
+    },
+    "expose-port": {
+      "description": "Expose a port to the network. Use --help for more details.",
+      "allowHelp": true,
+      "command": "cladding",
+      "args": ["expose"]
+    }
+  }
 }

package/templates/environments/cladding/run-with-network.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write(
+    `run-with-network: Run a command with network access via cladding's sandbox.\n` +
+      `\n` +
+      `Usage:\n` +
+      `  run-with-network --command "<shell command>"\n` +
+      `\n` +
+      `The command string is forwarded to \`sh -c\` inside the cladding sandbox,\n` +
+      `so it supports pipes, redirection, &&, ||, environment variables, multiple\n` +
+      `commands, etc.\n` +
+      `\n` +
+      `Examples:\n` +
+      `  run-with-network --command "curl -sSL https://example.com | jq ."\n` +
+      `  run-with-network --command "FOO=1 echo \\$FOO"\n` +
+      `  run-with-network --command 'echo "hello" && echo "world"'\n`
+  );
+  process.exit(0);
+}
+
+const idx = args.indexOf('--command');
+if (idx === -1 || idx + 1 >= args.length) {
+  process.stderr.write(
+    `Error: --command <shell command> is required.\n` +
+      `Usage: run-with-network --command "<shell command>"\n`
+  );
+  process.exit(2);
+}
+const command = args[idx + 1];
+
+// `cladding run-with-scissors` execs its argv directly inside the sandbox, so
+// shell features (env-var prefixes, &&, pipes, multi-line) only work if we
+// hand it an explicit shell. Wrap in `sh -c` so the user's command string is
+// parsed as a script.
+const child = spawn('cladding', ['run-with-scissors', 'sh', '-c', command], {
+  stdio: ['ignore', 'inherit', 'inherit'],
+});
+
+child.on('close', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? 1);
+});
+
+child.on('error', (err) => {
+  process.stderr.write(`Failed to execute command: ${err.message}\n`);
+  process.exit(1);
+});

package/templates/environments/macos-proxy/allowlist-domain.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const allowlistPath = path.join(__dirname, 'allowlist.txt');
+
+const domains = process.argv.slice(2).filter((arg) => arg.length > 0);
+if (domains.length === 0) {
+  console.error('Usage: allowlist-domain <domain> [<domain>...]');
+  process.exit(1);
+}
+
+const domainPattern = /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
+for (const domain of domains) {
+  if (!domainPattern.test(domain)) {
+    console.error(`Invalid domain: ${domain}`);
+    process.exit(1);
+  }
+}
+
+// O_NOFOLLOW on both read and write: a symlink at the allowlist path would
+// otherwise redirect host-privileged writes to an attacker-chosen file.
+function readAllowlist() {
+  let fd;
+  try {
+    fd = fs.openSync(allowlistPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  } catch (err) {
+    if (err.code === 'ENOENT') return '';
+    if (err.code === 'ELOOP') {
+      console.error(`Refusing to follow symlink at allowlist path: ${allowlistPath}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  try {
+    const st = fs.fstatSync(fd);
+    const buf = Buffer.alloc(st.size);
+    fs.readSync(fd, buf, 0, st.size, 0);
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function appendAllowlist(text) {
+  let fd;
+  try {
+    fd = fs.openSync(
+      allowlistPath,
+      fs.constants.O_WRONLY |
+        fs.constants.O_APPEND |
+        fs.constants.O_CREAT |
+        fs.constants.O_NOFOLLOW,
+      0o644
+    );
+  } catch (err) {
+    if (err.code === 'ELOOP') {
+      console.error(`Refusing to follow symlink at allowlist path: ${allowlistPath}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  try {
+    fs.writeSync(fd, text);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+const existing = readAllowlist();
+const existingDomains = new Set(
+  existing
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith('#'))
+);
+
+const added = [];
+for (const domain of domains) {
+  if (!existingDomains.has(domain)) {
+    existingDomains.add(domain);
+    added.push(domain);
+  }
+}
+
+if (added.length === 0) {
+  console.log('No new domains to add; allowlist already contains all requested domains.');
+  process.exit(0);
+}
+
+const appendSuffix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+appendAllowlist(`${appendSuffix}${added.join('\n')}\n`);
+console.log(`Added ${added.length} domain(s) to allowlist: ${added.join(', ')}`);

package/templates/environments/macos-proxy/env.json

@@ -10,5 +10,12 @@
     "https_proxy": "http://127.0.0.1:8888",
     "PATH": "{PATH}:{WORKSPACE_DIR}/.local/bin"
   },
-  "exportLiteTo": ".local/bin/clawmini-lite.js"
+  "exportLiteTo": ".local/bin/clawmini-lite.js",
+  "policies": {
+    "allowlist-domain": {
+      "description": "Add one or more domains to the proxy allowlist. Usage: allowlist-domain <domain> [<domain>...]",
+      "command": "./allowlist-domain.mjs",
+      "allowHelp": false
+    }
+  }
 }

package/templates/environments/macos-proxy/proxy.mjs

@@ -5,7 +5,6 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// eslint-disable-next-line no-undef
 const envDir = process.env.ENV_DIR || __dirname;
 const allowlistPath = path.join(envDir, 'allowlist.txt');
 
@@ -28,10 +27,13 @@ function isAllowed(hostname) {
 }
 
 const server = http.createServer((req, res) => {
+  req.on('error', (err) => console.error('[HTTP] Client request error:', err.message));
+  res.on('error', (err) => console.error('[HTTP] Client response error:', err.message));
+
   try {
     const url = new URL(req.url);
     if (!isAllowed(url.hostname)) {
-      console.log(`[${new Date().toISOString()}] [HTTP] Blocked: ${url.hostname}`);
+      console.log(`[HTTP] Blocked: ${url.hostname}`);
       res.writeHead(403);
       res.end('Domain not allowed by proxy allowlist\n');
       return;
@@ -45,32 +47,44 @@ const server = http.createServer((req, res) => {
         headers: req.headers,
       },
       (proxyRes) => {
+        proxyRes.on('error', (err) => console.error('[HTTP] Proxy response error:', err.message));
         res.writeHead(proxyRes.statusCode, proxyRes.headers);
         proxyRes.pipe(res, { end: true });
       }
     );
-    req.pipe(proxyReq, { end: true });
+
     proxyReq.on('error', (err) => {
-      res.writeHead(500);
+      console.error('[HTTP] Proxy request error:', err.message);
+      if (!res.headersSent) {
+        res.writeHead(500);
+      }
       res.end(err.message);
     });
-  } catch {
-    res.writeHead(400);
+
+    req.pipe(proxyReq, { end: true });
+  } catch (err) {
+    console.error('[HTTP] Error handling request:', err.message);
+    if (!res.headersSent) {
+      res.writeHead(400);
+    }
     res.end('Bad request');
   }
 });
 
 server.on('connect', (req, clientSocket, head) => {
+  clientSocket.on('error', (err) => {
+    console.error(`[HTTPS] Client socket error:`, err.message);
+    clientSocket.destroy();
+  });
+
   try {
     const { port, hostname } = new URL(`http://${req.url}`);
     if (!isAllowed(hostname)) {
-      // Log the domain and timestamp
-      console.log(`[${new Date().toISOString()}] [HTTPS] Blocked: ${hostname}`);
+      console.log(`[HTTPS] Blocked: ${hostname}`);
       clientSocket.write('HTTP/1.1 403 Forbidden\r\n\r\nDomain not allowed by proxy allowlist\n');
       clientSocket.end();
       return;
     }
-    // Only log blocked domains for now
     // console.log(`[HTTPS] Allowed: ${hostname}`);
 
     const serverSocket = net.connect(port || 443, hostname, () => {
@@ -79,13 +93,28 @@ server.on('connect', (req, clientSocket, head) => {
       serverSocket.pipe(clientSocket);
       clientSocket.pipe(serverSocket);
     });
-    serverSocket.on('error', () => clientSocket.end());
-    clientSocket.on('error', () => serverSocket.end());
-  } catch {
-    clientSocket.end();
+
+    serverSocket.on('error', (err) => {
+      console.error(`[HTTPS] Server socket error for ${hostname}:`, err.message);
+      clientSocket.destroy();
+    });
+
+    // Update client error handler to also destroy serverSocket if it exists
+    clientSocket.removeAllListeners('error');
+    clientSocket.on('error', (err) => {
+      console.error(`[HTTPS] Client socket error for ${hostname}:`, err.message);
+      serverSocket.destroy();
+    });
+  } catch (err) {
+    console.error(`[HTTPS] Connection error:`, err.message);
+    clientSocket.destroy();
   }
 });
 
+server.on('error', (err) => {
+  console.error('Proxy server error:', err);
+});
+
 server.listen(8888, () => {
   console.log('Proxy listening on port 8888');
 });

package/templates/gemini/template.json

@@ -0,0 +1,5 @@
+{
+  "files": {
+    ".gemini/": "track"
+  }
+}

package/templates/gemini-claw/template.json

@@ -0,0 +1,13 @@
+{
+  "files": {
+    "GEMINI.md": "seed-once",
+    ".gemini/": "track",
+    "SOUL.md": "seed-once",
+    "USER.md": "seed-once",
+    "MEMORY.md": "seed-once",
+    "memory/": "seed-once",
+    "BOOTSTRAP.md": "seed-once",
+    "TOOLS.md": "seed-once",
+    "HEARTBEAT.md": "seed-once"
+  }
+}

package/templates/skills/clawmini-requests/SKILL.md

@@ -21,6 +21,18 @@ clawmini-lite.js requests list
 
 This will output the available policy names and their descriptions.
 
+### Inspecting a Single Policy
+
+To see the full definition of a policy (its underlying command, args, and flags like `autoApprove` / `allowHelp`):
+
+```bash
+clawmini-lite.js requests show <policy-name>
+```
+
+The output is JSON, followed by the script body when the policy's command points at a file inside `.clawmini/policy-scripts/`. Policies that wrap a system command print only the JSON — there is no script body to show, and the daemon refuses to read paths outside `policy-scripts/`. Reading is unrestricted — no approval is needed.
+
+If the script body is large, it is copied to `./tmp/policy-script-<name><ext>` instead of being printed inline; `requests show` will tell you the path so you can `cat` or `Read` it on demand.
+
 ### Getting Help for a Policy
 
 If a policy supports it, you can query it for help to understand what arguments it expects:
@@ -55,34 +67,81 @@ clawmini-lite.js request send-email --file body_txt=./report.txt -- --to admin@e
 
 ### What Happens Next
 
-When you submit a request, the CLI immediately returns a **Request ID** without blocking.
-The request is sent to the user's chat interface for review.
+When you submit a request, the CLI usually returns a **Request ID** without blocking. **The request has not run yet** — it is queued for the user to review, and the underlying command will only execute once the user approves it.
+
+When the user approves (or rejects) the request, the result will arrive as a **new user message in this chat**. **Do not poll** — do not run `requests show`, re-invoke the request, or otherwise loop checking for status. Finish any unrelated work that does not depend on this request, then end your turn with a brief message explaining you are blocked on this request.
 
 - **If Approved:** The policy executes securely, and the STDOUT/STDERR results will be automatically sent back to you in the chat.
 - **If Rejected:** The user may provide a reason for the rejection, allowing you to correct your request and try again.
 
-## Proposing New Policies
+## Managing Policies
+
+The built-in `manage-policies` policy lets you add, update, or remove policies. Each invocation goes through the same approval workflow as any other policy — the user reviews exactly which subcommand and arguments you proposed before anything mutates `policies.json`. Reads do not go through this script; use `requests show <name>` (above) for read access.
 
-If you need to perform an action that isn't covered by an existing policy, you can propose a new one using the default `propose-policy` policy. This allows you to request the creation of a new permission wrapper.
+The script has three subcommands: `add`, `update`, `remove`.
 
-**Important Note for Large Outputs:** If a policy or command produces massive output (like raw API JSON responses), it will overwhelm your context window. In these cases, it is strongly recommended to propose a custom policy script that uses tools like `jq` to parse, filter, and condense the data *before* it is returned to you.
+**Important Note for Large Outputs:** If a policy or command produces massive output (like raw API JSON responses), it will overwhelm your context window. In these cases, it is strongly recommended to register a custom policy script that uses tools like `jq` to parse, filter, and condense the data _before_ it is returned to you.
 
-You must provide a `--name` and `--description`, and either a shell `--command` or a `--script-file`.
+### Adding a New Policy (`add`)
+
+Provide a `--name` and `--description`, and either a shell `--command` or a `--script-file`. The script refuses to overwrite an existing entry — use `update` (below) if the name already exists.
+
+By default a new policy is **safe**: every invocation requires the user to approve it, and `--help` requests are blocked. You can opt in to looser behavior with two flags — both are prefixed `--dangerously-` because the user only sees them at proposal time:
+
+- `--dangerously-auto-approve`: future invocations of this policy run without the user reviewing each request. Only use for fully sandboxed, side-effect-free commands (e.g. read-only listings of local files). Never use for anything that mutates state, talks to the network, or spends money.
+- `--dangerously-allow-help`: lets you (the agent) run `<policy> --help` without approval. Safe only if the underlying command actually treats `--help` as read-only — many CLIs do, but custom scripts may not.
+
+If neither flag is set, both default to `false`. Prefer the safe default; only request the dangerous flags when you can justify them in the policy description.
 
 **Examples:**
 
-1. **Propose a simple command wrapper:**
+1. **A simple command wrapper (safe defaults):**
 
    ```bash
-   clawmini-lite.js request propose-policy -- --name npm-install --description "Run npm install globally" --command "npm install -g"
+   clawmini-lite.js request manage-policies -- add --name npm-install --description "Run npm install globally" --command "npm install -g"
    ```
 
-2. **Propose a custom script wrapper:**
+2. **A custom script wrapper:**
    First, write your complex logic to a file (e.g., `./script.sh`). **Note: The script file path MUST be inside your allowed workspace directory or use relative paths.**
+
+   ```bash
+   clawmini-lite.js request manage-policies --file script=./script.sh -- add --name custom-action --description "Run a custom deployment script" --script-file "{{script}}"
+   ```
+
+3. **A read-only policy that auto-approves and exposes `--help`:**
+
    ```bash
-   clawmini-lite.js request propose-policy --file script=./script.sh -- --name custom-action --description "Run a custom deployment script" --script-file "{{script}}"
+   clawmini-lite.js request manage-policies -- add --name list-files --description "List files in the workspace (read-only)" --command "ls" --dangerously-auto-approve --dangerously-allow-help
    ```
 
+### Updating an Existing Policy (`update`)
+
+Pass only the fields you want to change. The policy's name cannot be changed (`remove` + `add` if you need a rename).
+
+```bash
+clawmini-lite.js request manage-policies -- update --name <policy-name> [--description "..."] [--command "..."] [--script-file "{{script}}"] [--dangerously-auto-approve | --no-dangerously-auto-approve] [--dangerously-allow-help | --no-dangerously-allow-help]
+```
+
+The dangerous flags use the same bare-flag style as `add`: pass `--dangerously-auto-approve` to enable, `--no-dangerously-auto-approve` to disable, or omit it to leave the field unchanged.
+
+This refuses to update a built-in policy. If you need to override a built-in, register your own version with `add` first; subsequent updates target that override.
+
+If the policy is currently disabled (a `false` entry from `remove --disable-builtin`), `update` will tell you to clear the disable first via `remove --name <policy-name>` (without `--disable-builtin`), then re-register with `add`.
+
+### Removing a Policy (`remove`)
+
+Drops a registered policy entry:
+
+```bash
+clawmini-lite.js request manage-policies -- remove --name <policy-name>
+```
+
+To opt out of a built-in (write `false` so it stops being available even if its script is installed):
+
+```bash
+clawmini-lite.js request manage-policies -- remove --name <builtin-name> --disable-builtin
+```
+
 ## Creating New Skills for Policies
 
 When you discover or use a new policy frequently, you should create a dedicated Agent Skill for it. This guides developers and future agents on how to use the policy without needing to manually look up the `--help` each time.

package/templates/skills/run-host/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: run-host
+description: Last-resort escape hatch for running arbitrary shell commands on the host. Prefer registering a dedicated policy first.
+---
+
+# Run Host
+
+**Before using this, register a dedicated policy.** `run-host` is a generic escape hatch that forwards a command string to `sh -c`. It exists so you are never fully blocked, but it is the wrong tool for anything you will do more than once.
+
+For any task you can describe — running tests, installing a package, calling a specific API — use `manage-policies add` to register a named policy instead. Dedicated policies are easier for the user to review, can be auto-approved when safe, and give you a clear skill to call next time. Reach for `run-host` only when:
+
+- You need a genuinely one-off exploratory command (e.g. inspecting an unfamiliar file), **or**
+- You truly cannot express the task as a reusable policy.
+
+Because it can do anything the host shell can do, the user will be asked to approve every invocation, and repeated `run-host` requests for similar tasks are a signal that you should have registered a policy.
+
+## Usage
+
+Pass the command to run as a single string via `--command`. The string is forwarded to `sh -c`, so you can use pipes, redirection, and chained operators.
+
+```bash
+clawmini-lite.js request run-host -- --command "<your shell command>"
+```
+
+### Examples
+
+1. **Simple command:**
+
+   ```bash
+   clawmini-lite.js request run-host -- --command "ls -la"
+   ```
+
+2. **Pipes and redirection:**
+
+   ```bash
+   clawmini-lite.js request run-host -- --command "cat file.txt | grep error > errors.log"
+   ```
+
+3. **Chained commands:**
+
+   ```bash
+   clawmini-lite.js request run-host -- --command "npm install && npm test"
+   ```
+
+### Getting Help
+
+The policy supports `--help`, which prints argument documentation:
+
+```bash
+clawmini-lite.js request run-host --help
+```

package/templates/skills/skill-creator/SKILL.md

@@ -11,8 +11,8 @@ This document provides comprehensive instructions on how to create, structure, a
 
 You can create skills in two locations depending on their intended scope:
 
-- **Project-Specific:** Create skills in `.gemini/skills/<skill-name>/` at the root of your project. These will only be available when working within this project.
-- **Global:** Create skills in `~/.gemini/skills/<skill-name>/` in your home directory. These will be available to agents across all projects on your machine.
+- **Project-Specific:** Create skills in `.agents/skills/<skill-name>/` at the root of your project. These will only be available when working within this project.
+- **Global:** Create skills in `~/.agents/skills/<skill-name>/` in your home directory. These will be available to agents across all projects on your machine.
 
 ## 1. Specification & Directory Structure
 
@@ -21,7 +21,7 @@ A skill is defined by a directory containing a mandatory `SKILL.md` file. The di
 **Example Structure:**
 
 ```text
-.gemini/skills/my-awesome-skill/
+.agents/skills/my-awesome-skill/
 ├── SKILL.md         # Mandatory: Contains metadata and instructions
 ├── scripts/         # Optional: Executable code or helper scripts
 ├── references/      # Optional: Documentation or long-form context
@@ -47,6 +47,7 @@ The `SKILL.md` file must begin with YAML frontmatter containing metadata, follow
   - **Checklists:** Help the agent track progress in multi-step workflows.
   - **Validation Loops:** Instruct the agent to "Plan-Validate-Execute" (especially for destructive actions) to ensure correctness before execution.
 - **Calibrate Control:** Be highly prescriptive for fragile tasks, but allow flexibility for creative tasks. Provide clear defaults rather than a menu of options.
+- **Skill Validation:** Once you have generated a skill, you must always validate its folder structure and frontmatter by running `.agents/skills/skill-creator/scripts/validate.sh <path_to_skill_directory>`.
 
 ## 3. Optimizing Skill Descriptions