@machina.ai/cell-cli-core 1.41.1-rc2 → 1.45.1-rc2

package/dist/docs/cli/skills-best-practices.md

@@ -0,0 +1,78 @@
+# Agent Skill best practices
+
+Create high-quality, reliable Agent Skills by following these established design
+principles and patterns.
+
+## Design for discovery
+
+The most important part of a skill is its `description`. This is the only
+information the model has before activation.
+
+- **Be specific**: Use keywords that are likely to appear in user prompts (for
+  example, "audit," "security," "refactor," "migration").
+- **Define the trigger**: Clearly state _when_ the skill should be used (for
+  example, "Use this skill when the user asks to review a PR for performance
+  regressions").
+- **Avoid overlap**: Ensure your skill descriptions are distinct from one
+  another and from the general capabilities of the model.
+
+## Progressive disclosure
+
+The "context window" is a shared resource. Use a three-level loading system to
+manage context efficiently.
+
+1.  **Metadata (name + description)**: Always in context (~100 words).
+2.  **`SKILL.md` body**: Loaded only after the skill triggers (<5k words).
+3.  **Bundled resources**: Loaded only as needed by the model.
+
+**Best practice**: Keep the `SKILL.md` body focused on core procedural
+instructions. Move detailed reference material, schemas, and examples into
+separate files in a `references/` directory.
+
+## Degrees of freedom
+
+Match the level of instruction specificity to the task's fragility.
+
+- **High freedom (text-based instructions)**: Use when multiple approaches are
+  valid or decisions depend heavily on context.
+- **Medium freedom (pseudocode or scripts with parameters)**: Use when a
+  preferred pattern exists but some variation is acceptable.
+- **Low freedom (specific scripts, few parameters)**: Use when operations are
+  fragile and error-prone, or a specific sequence MUST be followed.
+
+## Bundle resources effectively
+
+Leverage the skill's ability to include scripts and assets to extend the agent's
+capabilities.
+
+- **Use scripts for deterministic tasks**: If a task can be automated with a
+  script (for example, running a linter, fetching data from an API), bundle it
+  in the `scripts/` folder.
+- **Agentic ergonomics**: Ensure scripts output LLM-friendly stdout. Suppress
+  verbose tracebacks and provide clear, concise success/failure messages.
+- **Provide templates**: Include common file headers or boilerplate code in the
+  `assets/` folder to ensure the agent produces consistent output.
+
+## Anatomy of a great skill
+
+A well-structured skill directory organizes its resources into specialized
+sub-folders.
+
+```text
+my-skill/
+├── SKILL.md       (Required) Core instructions and metadata
+├── scripts/       (Optional) Executable logic (Node.js, Python, etc.)
+├── references/    (Optional) Documentation to be loaded as needed
+└── assets/        (Optional) Templates and non-executable resources
+```
+
+## Security and privacy
+
+Design your skills with security in mind to protect your workspace and data.
+
+- **Avoid hardcoded secrets**: Never include API keys or passwords in your
+  skill's scripts or documentation.
+- **Review third-party skills**: Inspect the `SKILL.md` and scripts of any skill
+  before installing it from an untrusted source.
+- **Limit scope**: Design skills to be as focused as possible to minimize the
+  potential impact of errors.

package/dist/docs/cli/skills.md

@@ -1,221 +1,143 @@
 # Agent Skills
 
-Agent Skills allow you to extend Cell CLI with specialized expertise, procedural
+Agent Skills let you extend Gemini CLI with specialized expertise, procedural
 workflows, and task-specific resources. Based on the
 [Agent Skills](https://agentskills.io) open standard, a "skill" is a
 self-contained directory that packages instructions and assets into a
 discoverable capability.
 
-## Overview
-
-Unlike general context files ([`GEMINI.md`](./gemini-md.md)), which provide
+Unlike general context files ([GEMINI.md](./gemini-md.md)), which provide
 persistent workspace-wide background, Skills represent **on-demand expertise**.
-This allows Gemini to maintain a vast library of specialized capabilities—such
-as security auditing, cloud deployments, or codebase migrations—without
-cluttering the model's immediate context window.
+This lets Gemini CLI maintain a vast library of specialized capabilities—such as
+security auditing, cloud deployments, or codebase migrations—without cluttering
+the model's immediate context window.
 
-Gemini autonomously decides when to employ a skill based on your request and the
-skill's description. When a relevant skill is identified, the model "pulls in"
-the full instructions and resources required to complete the task using the
-`activate_skill` tool.
+## How it works
 
-## Key Benefits
+The lifecycle of an Agent Skill involves discovery, activation, and conditional
+resource access.
 
-- **Shared Expertise:** Package complex workflows (like a specific team's PR
-  review process) into a folder that anyone can use.
-- **Repeatable Workflows:** Ensure complex multi-step tasks are performed
-  consistently by providing a procedural framework.
-- **Resource Bundling:** Include scripts, templates, or example data alongside
-  instructions so the agent has everything it needs.
-- **Progressive Disclosure:** Only skill metadata (name and description) is
-  loaded initially. Detailed instructions and resources are only disclosed when
-  the model explicitly activates the skill, saving context tokens.
+> > > > > > > release/v0.29.5
 
-## Skill Discovery Tiers
+1.  **Discovery**: At the start of a session, Cell CLI scans the discovery tiers
+    and injects the name and description of all enabled skills into the system
+    prompt.
+2.  **Activation**: When Gemini identifies a task matching a skill's
+    description, it calls the `activate_skill` tool.
+3.  **Consent**: You will see a confirmation prompt in the UI detailing the
+    skill's name, purpose, and the directory path it will gain access to.
+4.  **Injection**: Upon your approval:
+    - The `SKILL.md` body and folder structure is added to the conversation
+      history.
+    - The skill's directory is added to the agent's allowed file paths, granting
+      it permission to read any bundled assets.
+5.  **Execution**: The model proceeds with the specialized expertise active. It
+    is instructed to prioritize the skill's procedural guidance within reason.
+
+## Discovery tiers
 
-Cell CLI discovers skills from three primary locations:
+Gemini CLI discovers skills from several locations, following a specific order
+of precedence (lowest to highest):
 
-1.  **Workspace Skills**: Located in `.cell-cli/skills/` or the
-    `.agents/skills/` alias. Workspace skills are typically committed to version
-    control and shared with the team.
-2.  **User Skills**: Located in `~/.cell-cli/skills/` or the `~/.agents/skills/`
-    alias. These are personal skills available across all your workspaces.
-3.  **Extension Skills**: Skills bundled within installed
+1.  **Built-in skills**: Standard skills included with Gemini CLI that provide
+    foundational capabilities.
+2.  **Extension skills**: Skills bundled within installed
     [extensions](../extensions/index.md).
+3.  **User skills**: Located in `~/.gemini/skills/` or the `~/.agents/skills/`
+    alias.
+4.  **Workspace skills**: Located in `.gemini/skills/` or the `.agents/skills/`
+    alias. Workspace skills are shared with your team via version control.
 
-**Precedence:** If multiple skills share the same name, higher-precedence
-locations override lower ones: **Workspace > User > Extension**.
+### Precedence and aliases
 
-Within the same tier (user or workspace), the `.agents/skills/` alias takes
-precedence over the `.cell-cli/skills/` directory. This generic alias provides
-an intuitive path for managing agent-specific expertise that remains compatible
-across different AI agent tools.
+If multiple skills share the same name, the version from the higher-precedence
+location is used. Within the same tier (user or workspace), the
+`.agents/skills/` alias takes precedence over the `.gemini/skills/` directory.
 
-## Managing Skills
+The `.agents/skills/` alias provides an interoperable path for managing
+agent-specific expertise that remains compatible across different AI tools.
 
-### In an Interactive Session
+## Key benefits
 
-Use the `/skills` slash command to view and manage available expertise:
+Agent Skills provide several advantages for managing specialized knowledge and
+complex workflows.
 
-- `/skills list` (default): Shows all discovered skills and their status.
-- `/skills link <path>`: Links agent skills from a local directory via symlink.
-- `/skills disable <name>`: Prevents a specific skill from being used.
-- `/skills enable <name>`: Re-enables a disabled skill.
-- `/skills reload`: Refreshes the list of discovered skills from all tiers.
+- **Shared expertise**: Package complex workflows (like a specific team's PR
+  review process) into a folder that anyone can use.
+- **Repeatable workflows**: Ensure complex multi-step tasks are performed
+  consistently by providing a procedural framework.
+- **Resource bundling**: Include scripts, templates, or example data alongside
+  instructions so the agent has everything it needs.
+- **Progressive disclosure**: Only skill metadata (name and description) is
+  loaded initially. Detailed instructions and resources are only disclosed when
+  the model explicitly activates the skill, saving context tokens.
 
 <!-- prettier-ignore -->
 > [!NOTE]
 > `/skills disable` and `/skills enable` default to the `user` scope. Use
 > `--scope workspace` to manage workspace-specific settings.
 
-### From the Terminal
-
-The `gemini skills` command provides management utilities:
-
-```bash
-# List all discovered skills
-gemini skills list
-
-# Link agent skills from a local directory via symlink
-# Discovers skills (SKILL.md or */SKILL.md) and creates symlinks in ~/.cell-cli/skills
-# (or ~/.agents/skills)
-gemini skills link /path/to/my-skills-repo
-
-# Link to the workspace scope (.cell-cli/skills or .agents/skills)
-gemini skills link /path/to/my-skills-repo --scope workspace
-
-# Install a skill from a Git repository, local directory, or zipped skill file (.skill)
-# Uses the user scope by default (~/.cell-cli/skills or ~/.agents/skills)
-gemini skills install https://github.com/user/repo.git
-gemini skills install /path/to/local/skill
-gemini skills install /path/to/local/my-expertise.skill
-
-# Install a specific skill from a monorepo or subdirectory using --path
-gemini skills install https://github.com/my-org/my-skills.git --path skills/frontend-design
-
-# Install to the workspace scope (.cell-cli/skills or .agents/skills)
-gemini skills install /path/to/skill --scope workspace
+To see all available skills in your current session, use the `/skills list`
+command.
 
-# Uninstall a skill by name
-gemini skills uninstall my-expertise --scope workspace
+## Managing skills
 
-# Enable a skill (globally)
-gemini skills enable my-expertise
+You can manage Agent Skills through interactive session commands or directly
+from your terminal.
 
-# Disable a skill. Can use --scope to specify workspace or user (defaults to workspace)
-gemini skills disable my-expertise --scope workspace
-```
-
-<<<<<<< HEAD
-
-## Creating a Skill
-
-A skill is a directory containing a `SKILL.md` file at its root. This file uses
-YAML frontmatter for metadata and Markdown for instructions.
-
-### Folder Structure
-
-Skills are self-contained directories. At a minimum, a skill requires a
-`SKILL.md` file, but can include other resources:
-
-```text
-my-skill/
-├── SKILL.md       (Required) Instructions and metadata
-├── scripts/       (Optional) Executable scripts/tools
-├── references/    (Optional) Static documentation and examples
-└── assets/        (Optional) Templates and binary resources
-```
-
-### Basic Structure (SKILL.md)
-
-```markdown
----
-name: <unique-name>
-description: <what the skill does and when Gemini should use it>
----
+### In an interactive session
 
-<your instructions for how the agent should behave / use the skill>
-```
-
-- **`name`**: A unique identifier (lowercase, alphanumeric, and dashes).
-- **`description`**: The most critical field. Gemini uses this to decide when
-  the skill is relevant. Be specific about the expertise provided.
-- **Body**: Everything below the second `---` is injected as expert procedural
-  guidance for the model.
-
-### Example: Team Code Reviewer
+Use the `/skills` slash command to view and manage available expertise:
 
-Create `~/.cell-cli/skills/code-reviewer/SKILL.md`:
+- `/skills list [all] [nodesc]`: Shows discovered skills. Use `all` to include
+  built-in skills and `nodesc` to hide descriptions.
+- `/skills link <path> [--scope user|workspace]`: Links skills from a local
+  directory.
+- `/skills disable <name>`: Prevents a specific skill from being used.
+- `/skills enable <name>`: Re-enables a disabled skill.
+- `/skills reload` (or `/skills refresh`): Refreshes the list of discovered
+  skills from all tiers.
 
-```markdown
----
-name: code-reviewer
-description:
-  Expertise in reviewing code for style, security, and performance. Use when the
-  user asks for "feedback," a "review," or to "check" their changes.
----
+### From the terminal
 
-# Code Reviewer
+The `gemini skills` command provides management utilities:
 
-You are an expert code reviewer. When reviewing code, follow this workflow:
+```bash
+# List all discovered skills. Use --all to include built-in skills.
+gemini skills list --all
 
-1.  **Analyze**: Review the staged changes or specific files provided. Ensure
-    that the changes are scoped properly and represent minimal changes required
-    to address the issue.
-2.  **Style**: Ensure code follows the workspace's conventions and idiomatic
-    patterns as described in the `GEMINI.md` file.
-3.  **Security**: Flag any potential security vulnerabilities.
-4.  **Tests**: Verify that new logic has corresponding test coverage and that
-    the test coverage adequately validates the changes.
+# Install a skill from a Git repository or local directory.
+# Use --consent to skip the security confirmation prompt.
+gemini skills install https://github.com/user/repo.git --consent
 
-Provide your feedback as a concise bulleted list of "Strengths" and
-"Opportunities."
+# Uninstall a skill.
+gemini skills uninstall my-skill --scope workspace
 ```
 
-### Resource Conventions
-
-While you can structure your skill directory however you like, the Agent Skills
-standard encourages these conventions:
-
-- **`scripts/`**: Executable scripts (bash, python, node) the agent can run.
-- **`references/`**: Static documentation, schemas, or example data for the
-  agent to consult.
-- **`assets/`**: Code templates, boilerplate, or binary resources.
+#### Command options
 
-When a skill is activated, Cell CLI provides the model with a tree view of the
-entire skill directory, allowing it to discover and utilize these assets.
+The skill management commands support several global and command-specific
+options.
 
-## How it Works (Security & Privacy)
-
-=======
-
-## How it Works
-
-> > > > > > > release/v0.29.5
-
-1.  **Discovery**: At the start of a session, Cell CLI scans the discovery tiers
-    and injects the name and description of all enabled skills into the system
-    prompt.
-2.  **Activation**: When Gemini identifies a task matching a skill's
-    description, it calls the `activate_skill` tool.
-3.  **Consent**: You will see a confirmation prompt in the UI detailing the
-    skill's name, purpose, and the directory path it will gain access to.
-4.  **Injection**: Upon your approval:
-    - The `SKILL.md` body and folder structure is added to the conversation
-      history.
-    - The skill's directory is added to the agent's allowed file paths, granting
-      it permission to read any bundled assets.
-5.  **Execution**: The model proceeds with the specialized expertise active. It
-    is instructed to prioritize the skill's procedural guidance within reason.
+- `--scope`: Either `user` (global, default) or `workspace` (local to the
+  project).
+- `--path`: The sub-directory within a Git repository containing the skill.
+- `--consent`: Acknowledge security risks and skip the interactive confirmation
+  during installation.
 
-### Skill activation
+For more details on CLI commands, see the
+[CLI reference](./cli-reference.md#skills-management).
 
-Once a skill is activated (typically by Gemini identifying a task that matches
-the skill's description and your approval), its specialized instructions and
-resources are loaded into the agent's context. A skill remains active and its
-guidance is prioritized for the duration of the session.
+## Next steps
 
-## Creating your own skills
+Explore these resources to refine your skills and understand the framework
+better.
 
-To create your own skills, see the [Create Agent Skills](./creating-skills.md)
-guide.
+- [Get started with Agent Skills](./tutorials/skills-getting-started.md): A
+  quick walkthrough of triggering and using skills.
+- [Creating Agent Skills](./creating-skills.md): Create your first skill and
+  bundle custom logic.
+- [Using Agent Skills](./using-agent-skills.md): Learn how to leverage built-in
+  and custom skills.
+- [Best practices](./skills-best-practices.md): Learn strategies for building
+  effective skills.

package/dist/docs/cli/tutorials/memory-management.md

@@ -71,8 +71,8 @@ Just tell the agent to remember something.
 
 **Prompt:** `Remember that I prefer using 'const' over 'let' wherever possible.`
 
-The agent will use the `save_memory` tool to store this fact in your global
-memory file.
+The agent will edit the appropriate memory Markdown file, so the fact is loaded
+in future sessions.
 
 **Prompt:** `Save the fact that the staging server IP is 10.0.0.5.`
 
@@ -125,4 +125,4 @@ immediately. Force a reload with:
   `/memory` options.
 - Read the technical spec for [Project context](../../cli/gemini-md.md).
 - Try the experimental [Auto Memory](../auto-memory.md) feature to extract
-  reusable skills from your past sessions automatically.
+  memory updates and reusable skills from your past sessions automatically.

package/dist/docs/cli/tutorials/session-management.md

@@ -61,6 +61,19 @@ cell-cli --list-sessions
 cell-cli --delete-session 1
 ```
 
+### Scenario: Delete session on exit
+
+If you're doing a one-off task and don't want to leave any session history
+behind, use the `--delete` flag when exiting:
+
+```
+/exit --delete
+```
+
+This removes the current session's conversation history and tool output files
+before exiting. It's useful for privacy-sensitive tasks or quick one-off
+interactions.
+
 ## How to rewind time (Undo mistakes)
 
 Cell CLI's **Rewind** feature is like `Ctrl+Z` for your workflow.