esso0428-pi-skill-tags

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# @esso0428/pi-skill-tags

Inline Pi skills anywhere in a prompt with searchable `$` autocomplete and compact, theme-aware tags.

![Pi prompt editor showing inline skill tags](https://github.com/esso0428/pi-skill-tags/raw/HEAD/docs/skill-tags.png)

## Features

- Opens skill autocomplete when you type `$`
- Finds loaded project, global, and temporary skills
- Inserts explicit `$[skill-name]` tags
- Renders known tags as width-preserving TUI chips
- Expands tags into Pi's native skill format on submission
- Loads repeated skills once and combines multiple skills into one invocation
- Leaves unknown or unreadable tags unchanged

## Example

```text
Prompt editor
┌──────────────────────────────────────────────────────────────┐
│ Review this diff with ✦ review-code  then ✦ write-tests     │
└──────────────────────────────────────────────────────────────┘

Submitted prompt
<skill name="review-code + write-tests" location="multiple skills">
  …trusted instructions from both skills…
</skill>

Review this diff with review-code then write-tests
```

The chip is cosmetic. The underlying editor text remains `$[review-code]` or `$[write-tests]`.

## Install

From npm:

```bash
pi install npm:@esso0428/pi-skill-tags
```

From GitHub:

```bash
pi install git:github.com/esso0428/pi-skill-tags
```

From a local checkout:

```bash
pi install ./pi-skill-tags
```

Use `-l` with any `pi install` command for project-local package configuration. Restart Pi or run `/reload` after installation or updates.

## Usage

1. Type `$` in the prompt editor.
2. Continue typing to filter loaded skills.
3. Select a suggestion, or write a tag directly as `$[name]`.
4. Submit the prompt normally.

Autocomplete labels each skill by scope:

- **Project skill** — loaded from the current project's skill directories
- **Global skill** — loaded from user-level skill directories
- **Temporary skill** — loaded only for the current Pi invocation

Multiple tags collapse into one Pi skill invocation. Repeated tags load the skill only once:

```text
Use $[review-code] on this diff, then $[write-tests] for the fix.
```

Unknown tags stay as plain text rather than being removed.

## Compatibility

- Pi `0.80.7` is the currently tested release.
- Node.js `22.19` or newer is required for development and package installation.
- The package declares Pi's coding-agent and TUI APIs as `*` peer dependencies, as required by the Pi package format.

## Security

Skills are trusted instructions. When a tag is submitted, this extension reads that skill and places its instructions in the model context; those instructions can direct the model to run commands or modify files. Review skills and packages before using them. Pi extensions themselves run with full system access.

## Limitations

- Only loaded skills appear in autocomplete.
- Tags use skill names containing letters, numbers, `_`, or `-`.
- Unreadable skill files remain unexpanded.
- The editor integration is intentionally narrow: it wraps only `render()` for cosmetic tag decoration and delegates all other editor behavior to the active editor.

## Development

```bash
npm install
npm run setup-hooks
npm run check
npm pack --dry-run
```

Tests use Node's built-in test runner. TypeScript is loaded directly; no build output is published. The npm package allowlist contains only the two runtime source files and public documentation.

To test a checkout in Pi without copying it:

```bash
pi -e ./pi-skill-tags
```

### Intentional main-branch release gate

This repo can enforce an intentional `main` push workflow through `.githooks/pre-push`:

1. publish the version to npm first
2. wait until npm can resolve that version
3. push `main`

Enable it locally with:

```bash
npm run setup-hooks
```

You can manually verify the same rule without pushing:

```bash
npm run check:release-gate
```

If the hook blocks a push, the failure message is intentional and explains the required publish-first workflow. Temporary bypass is still possible with:

```bash
SKIP_NPM_GATE=1 git push
```

## Release and publishing

1. Update `version` in `package.json` and `package-lock.json`.
2. Add the release notes to `CHANGELOG.md`.
3. Run `npm ci`, `npm run check`, and `npm pack --dry-run`.
4. Create a matching tag such as `v0.1.0`.
5. Push the tag to GitHub. The publish workflow verifies that the tag matches the package version, then publishes with npm provenance and public access.

Configure the GitHub Actions secret `NPM_TOKEN` with an npm granular access token that has **Read and write** permission for `@esso0428/pi-skill-tags` and **Bypass 2FA** enabled. The first scoped publish must permit public access; `publishConfig` and the workflow both enforce it.

## License

[MIT](https://github.com/esso0428/pi-skill-tags/tree/HEAD/LICENSE)

@esso0428/pi-skill-tags

Inline Pi skills anywhere in a prompt with searchable $ autocomplete and compact, theme-aware tags.

Pi prompt editor showing inline skill tags

Features

Opens skill autocomplete when you type $
Finds loaded project, global, and temporary skills
Inserts explicit $[skill-name] tags
Renders known tags as width-preserving TUI chips
Expands tags into Pi's native skill format on submission
Loads repeated skills once and combines multiple skills into one invocation
Leaves unknown or unreadable tags unchanged

Example

Prompt editor
┌──────────────────────────────────────────────────────────────┐
│ Review this diff with ✦ review-code  then ✦ write-tests     │
└──────────────────────────────────────────────────────────────┘

Submitted prompt
<skill name="review-code + write-tests" location="multiple skills">
  …trusted instructions from both skills…
</skill>

Review this diff with review-code then write-tests

The chip is cosmetic. The underlying editor text remains $[review-code] or $[write-tests].

Install

From npm:

pi install npm:@esso0428/pi-skill-tags

From GitHub:

pi install git:github.com/esso0428/pi-skill-tags

From a local checkout:

pi install ./pi-skill-tags

Use -l with any pi install command for project-local package configuration. Restart Pi or run /reload after installation or updates.

Usage

Type $ in the prompt editor.
Continue typing to filter loaded skills.
Select a suggestion, or write a tag directly as $[name].
Submit the prompt normally.

Autocomplete labels each skill by scope:

Project skill — loaded from the current project's skill directories
Global skill — loaded from user-level skill directories
Temporary skill — loaded only for the current Pi invocation

Multiple tags collapse into one Pi skill invocation. Repeated tags load the skill only once:

Use $[review-code] on this diff, then $[write-tests] for the fix.

Unknown tags stay as plain text rather than being removed.

Compatibility

Pi 0.80.7 is the currently tested release.
Node.js 22.19 or newer is required for development and package installation.
The package declares Pi's coding-agent and TUI APIs as * peer dependencies, as required by the Pi package format.

Security

Skills are trusted instructions. When a tag is submitted, this extension reads that skill and places its instructions in the model context; those instructions can direct the model to run commands or modify files. Review skills and packages before using them. Pi extensions themselves run with full system access.

Limitations

Only loaded skills appear in autocomplete.
Tags use skill names containing letters, numbers, _, or -.
Unreadable skill files remain unexpanded.
The editor integration is intentionally narrow: it wraps only render() for cosmetic tag decoration and delegates all other editor behavior to the active editor.

Development

npm install
npm run setup-hooks
npm run check
npm pack --dry-run

Tests use Node's built-in test runner. TypeScript is loaded directly; no build output is published. The npm package allowlist contains only the two runtime source files and public documentation.

To test a checkout in Pi without copying it:

pi -e ./pi-skill-tags

Intentional main-branch release gate

This repo can enforce an intentional main push workflow through .githooks/pre-push:

publish the version to npm first
wait until npm can resolve that version
push main

Enable it locally with:

npm run setup-hooks

You can manually verify the same rule without pushing:

npm run check:release-gate

If the hook blocks a push, the failure message is intentional and explains the required publish-first workflow. Temporary bypass is still possible with:

SKIP_NPM_GATE=1 git push

Release and publishing

Update version in package.json and package-lock.json.
Add the release notes to CHANGELOG.md.
Run npm ci, npm run check, and npm pack --dry-run.
Create a matching tag such as v0.1.0.
Push the tag to GitHub. The publish workflow verifies that the tag matches the package version, then publishes with npm provenance and public access.

Configure the GitHub Actions secret NPM_TOKEN with an npm granular access token that has Read and write permission for @esso0428/pi-skill-tags and Bypass 2FA enabled. The first scoped publish must permit public access; publishConfig and the workflow both enforce it.

License

MIT