{"id":51407933,"url":"https://github.com/jpoindexter/skill-triggers","last_synced_at":"2026-07-04T12:30:21.256Z","repository":{"id":366689031,"uuid":"1277392511","full_name":"jpoindexter/skill-triggers","owner":"jpoindexter","description":"Declarative event-fired triggers for agent skills — compile a triggers: frontmatter field in any SKILL.md into Vanta and Claude Code hooks.","archived":false,"fork":false,"pushed_at":"2026-06-22T22:20:19.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-23T00:09:55.256Z","etag":null,"topics":["agent-skills","ai-agents","automation","claude-code","hooks","prompt-engineering","skills","vanta"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpoindexter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-22T21:20:54.000Z","updated_at":"2026-06-22T22:20:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jpoindexter/skill-triggers","commit_stats":null,"previous_names":["jpoindexter/skill-triggers"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jpoindexter/skill-triggers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpoindexter%2Fskill-triggers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpoindexter%2Fskill-triggers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpoindexter%2Fskill-triggers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpoindexter%2Fskill-triggers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpoindexter","download_url":"https://codeload.github.com/jpoindexter/skill-triggers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpoindexter%2Fskill-triggers/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35122497,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-agents","automation","claude-code","hooks","prompt-engineering","skills","vanta"],"created_at":"2026-07-04T12:30:19.706Z","updated_at":"2026-07-04T12:30:21.247Z","avatar_url":"https://github.com/jpoindexter.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# skill-triggers\n\n**Declarative event-fired triggers for agent skills.** Most agent \"skills\" (a `SKILL.md`\nfile of reusable know-how) only fire by *relevance* — the agent recalls them when a task\nlooks related. `skill-triggers` lets a skill declare it should fire on a specific **harness\nevent** (before a push, after repeated tool errors, on a prompt) by adding one frontmatter\nfield, then compiles that into hooks for **[Vanta](https://github.com/jpoindexter/Vanta)**\nand **Claude Code**.\n\n```yaml\n---\nname: ship-preflight\ndescription: Run the test suite before a push\ntriggers: [{\"event\":\"PreToolUse\",\"match\":\"git_push\"}]\n---\n```\n\n## The `triggers:` convention\n\nA single-line JSON array on a `triggers:` key. Each entry:\n\n| Field | Meaning |\n|---|---|\n| `event` | Harness event (e.g. `PreToolUse`, `PostToolUse`, `Stop`, `UserPromptSubmit`) |\n| `match` | (optional) regex on the tool name — `PreToolUse`/`PostToolUse` |\n| `when` | (optional) compact condition; `\"errors\u003e=N\"` fires on a tool error |\n| `action` | (optional) `\"block\"` makes a `PreToolUse` trigger a hard gate; default is advisory |\n| `note` | (optional) override the surfaced recall note |\n\nSingle-line keeps it parseable by the flat frontmatter readers both harnesses use.\n\n## Firing model — safe by design\n\nA trigger never *runs* the skill body or anything irreversible. It compiles to a hook that\nruns `vanta skills trigger-emit \u003cslug\u003e \u003cevent\u003e`, which only **surfaces a recall note** so the\nagent applies the know-how itself:\n\n- **`Stop`** → prints `{\"additionalContext\": \"…recall skill X…\"}` to stdout (model-facing injection).\n- **`PreToolUse`** → a heads-up to the user (advisory). With `action:\"block\"` it can hard-gate the tool.\n- **`UserPromptSubmit` / others** → prints the note to stdout (Claude Code injects it as context).\n\n## Which events inject context\n\n| Harness | Real context injection on |\n|---|---|\n| **Vanta** | `Stop` (`additionalContext`); `PreToolUse` can block/advise; `PostToolUse` on error |\n| **Claude Code** | `PreToolUse`, `UserPromptSubmit`, `Stop`, and tool errors (a `PostToolUse`+error trigger → `PostToolUseFailure`) — all via `hookSpecificOutput.additionalContext` |\n\nThe compiler degrades unsupported events to advisory rather than failing.\n\n### Cross-harness tool names\n\nClaude Code's tool names differ from Vanta's (a git push is a `Bash` call, not a `git_push`\ntool). The compiler maps `match` accordingly — `git_push` → matcher `Bash` + the emitter\nconfirms the command contains `git push` before firing — so a `PreToolUse` trigger behaves the\nsame in both harnesses, with no every-call noise. (`write_file`→`Write|Edit`, `read_file`→`Read`, …;\nunknown names pass through unchanged.)\n\n## Use it\n\n```bash\n# Print the Vanta hooks.json fragment for a skill\nnpx skill-triggers compile ./my-skill --target vanta\n\n# Merge it into ~/.vanta/hooks.json (idempotent; preserves hand-written hooks)\nnpx skill-triggers compile ./my-skill --target vanta --write\n\n# Or target Claude Code's ~/.claude/settings.json (Stop + UserPromptSubmit)\nnpx skill-triggers compile ./my-skill --target claude --write\n```\n\nRe-running is idempotent: generated entries are namespaced by the `skills trigger-emit`\ncommand marker, so they're cleanly replaced and your hand-written hooks are never touched.\n\n## Library\n\n```ts\nimport { parseSkill, compileToVanta, compileToClaude, mergeVanta } from \"skill-triggers\";\n\nconst skill = parseSkill(readFileSync(\"SKILL.md\", \"utf8\"));\nconst hooks = compileToVanta(skill);            // → [{ event, hook }]\nconst merged = mergeVanta(existingHooksJson, hooks);\n```\n\n## Status\n\nv0.1 — the convention + reference compiler + CLI, with cross-harness event mapping for Vanta and\nClaude Code: `PreToolUse` (tool-name-mapped), `Stop`, `UserPromptSubmit`, and tool errors\n(`PostToolUse`+error → `PostToolUseFailure`). The compiler is the reference implementation of the\n`triggers:` convention; Vanta ships a native integration of the same logic. Roadmap: an\n`agent`-mode firing option (run a skill as a worker) and an npm release Vanta consumes directly.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpoindexter%2Fskill-triggers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpoindexter%2Fskill-triggers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpoindexter%2Fskill-triggers/lists"}