open-index/open-npm huggingface dataset:
npm package: @gizmo-ai/skill-plugin
Description: Skill discovery and lifecycle plugin for Gizmo runtime
Latest version: 0.2.2

# @gizmo-ai/skill-plugin

Skill discovery and lifecycle plugin for Gizmo runtime. Implements the [Agent Skills specification](https://agentskills.io/specification).

## Installation

```bash
bun add @gizmo-ai/skill-plugin
```

## Usage

```typescript
import { skillPlugin } from "@gizmo-ai/skill-plugin";
import { agentPlugin } from "@gizmo-ai/agent-plugin";
import { createRuntime } from "@gizmo-ai/runtime";

const runtime = createRuntime({
  plugins: [
    skillPlugin({ cwd: process.cwd() }),
    agentPlugin({
      model: openAI(),
      systemMessage: baseSystemMessage
    })
  ]
});
```

Skills are automatically appended to the system prompt when the runtime initializes.

## Skill Discovery

Skills are discovered from:

- `~/.gizmo/skills/` (user-level skills)
- `.gizmo/skills/` (project-level skills)

### Skill Format

Skills follow the [Agent Skills specification](https://agentskills.io/specification). Create a `SKILL.md` file with YAML frontmatter:

```markdown
---
name: my-skill
description: A helpful skill for specific tasks
---

# My Skill

Instructions for the agent...
```

Or create subdirectories with `SKILL.md`:

```
.gizmo/skills/
  my-skill/
    SKILL.md
    templates/
      example.txt
```

## Actions

The plugin emits:

- `SKILL_SKILLS_DISCOVERED` - At startup with all discovered skills
- `SKILL_SKILL_LOADED` - When agent reads a skill file
- `SKILL_SKILL_CREATED` - When agent creates a new skill
- `SKILL_SKILL_REMOVED` - When a skill directory is deleted (via filesystem watch)

## API

### `skillPlugin(config)`

Create the skill plugin.

```typescript
const skills = skillPlugin({
  cwd: process.cwd(),      // Project directory (default: process.cwd())
  configDir: "~/.gizmo",   // User config directory (default: ~/.gizmo)
  skillPaths: []           // Additional skill paths
});
```

### `skills.getDiscoveredSkills()`

Get all discovered skills.

### `skills.isSkillLoaded(name)`

Check if a skill has been loaded.

### `skills.stopWatching()`

Stop filesystem watchers (for cleanup).

## Standalone Functions

```typescript
import {
  loadSkills,
  formatSkillsForPrompt,
  findSkillByPath
} from "@gizmo-ai/skill-plugin";

// Load skills from directories
const { skills, diagnostics } = loadSkills({ cwd: "/project" });

// Format for prompt
const promptXml = formatSkillsForPrompt(skills);

// Find skill by file path
const skill = findSkillByPath("/path/to/file.md", skills);
```
npm package: @gizmo-ai/tools
Description: Tool factories for Gizmo agents - file system and web tools
Latest version: 0.2.3

# @gizmo-ai/tools

Tool factories for Gizmo agents. Provides file system and web tools.

## Install

```bash
bun add @gizmo-ai/tools
```

## Usage

```typescript
import { createRuntime } from "@gizmo-ai/runtime";
import { agentPlugin } from "@gizmo-ai/agent-plugin";
import { fsTools, webTools } from "@gizmo-ai/tools";
import { openAI } from "@gizmo-ai/model-providers";

const runtime = createRuntime({
  plugins: [
    agentPlugin({
      model: openAI(),
      tools: [
        ...fsTools({ permissions: { allowedPaths: ["/tmp/**"] } }),
        ...webTools({ search: { provider: "brave", apiKey: "..." } }),
      ],
    }),
  ],
});
```

## File System Tools

`fsTools()` returns tools for file system operations:

| Tool | Description |
|------|-------------|
| `read` | Read file contents with optional line range |
| `write` | Create or overwrite files |
| `edit` | Make precise string replacements |
| `bash` | Execute shell commands |
| `glob` | Find files matching patterns |
| `grep` | Search file contents with regex |

### Configuration

```typescript
fsTools({
  // Enable/disable individual tools
  tools: {
    read: true,
    write: true,
    edit: true,
    bash: false,  // Disable bash
    glob: true,
    grep: true,
  },
  // Permission restrictions
  permissions: {
    allowedPaths: ["/tmp/**", "/home/user/projects/**"],
    deniedPaths: ["/etc/**", "/home/user/.ssh/**"],
    allowedBaseCommands: ["ls", "cat", "grep"],
    shellSafetyMode: "strict_tokenized", // or "sandbox_trust" (default)
    maxFileSize: 1024 * 1024,  // 1MB
  },
})
```

`shellSafetyMode` behavior:
- `sandbox_trust` (default): checks base command and blocks newlines, but still allows shell metacharacters.
- `strict_tokenized`: rejects shell metacharacters/chaining (`;`, `&&`, `||`, `|`, `$()`, redirects, etc.).

## Web Tools

`webTools()` returns tools for web operations:

| Tool | Description |
|------|-------------|
| `web_search` | Search the web for information |
| `web_fetch` | Fetch and parse web page content |

### Configuration

```typescript
webTools({
  // Enable/disable individual tools
  tools: {
    webSearch: true,
    webFetch: true,
  },
  // Search provider (required for web_search)
  search: {
    provider: "brave",  // or "tavily", "serper"
    apiKey: process.env.BRAVE_API_KEY,
  },
  // Fetch restrictions
  fetch: {
    allowedDomains: ["example.com"],
    deniedDomains: ["localhost", "127.0.0.1"],
    timeout: 10000,
    maxSize: 1024 * 1024,
  },
})
```

## License

MIT
npm package: @gizmo-ai/user-updates-plugin
Description: User-facing progress/final update plugin for Gizmo runtime
Latest version: 0.1.0

# @gizmo-ai/user-updates-plugin

User-facing progress/final/error update plugin for Gizmo runtime.

This plugin adds:
- `user_updates` state slice
- `user_update` tool (registered automatically)

## Usage

```ts
import { createRuntime } from "@gizmo-ai/runtime";
import { agentPlugin } from "@gizmo-ai/agent-plugin";
import { userUpdates } from "@gizmo-ai/user-updates-plugin";

const runtime = createRuntime({
  plugins: [
    agentPlugin({ model, tools: [] }),
    userUpdates({ maxUpdates: 200, toolName: "user_update" }),
  ],
});
```

The model can call:
- `user_update({ kind: "progress" | "final" | "error", message: string })`

Each call appends an entry to `state.user_updates.updates`.