ai-agents-skills

A cross-agent plugin that bundles skills, specialist prompts, and hooks for
running coding agents productively: a kanban
workflow, an autonomous timed task runner, Telegram notifications, and a few
utilities.

This repository also ships a Codex
plugin manifest (.codex-plugin/plugin.json) so the same skills can be used
from Codex CLI — see Install (Codex) below — and a
Cursor Agent CLI/IDE plugin
manifest (.cursor-plugin/plugin.json) — see Install (Cursor)
below — plus a Hermes Agent
plugin (plugin.yaml + __init__.py) — see Install (Hermes).
All four integrations share the same skills/ tree; see
AGENTS.md for the repo conventions that keep them in sync.

Agents

Claude, Codex, and Cursor auto-discover agents from agents/ and address them
as ai-agents-skills:<name>. Hermes exposes the same prompt bodies as read-only
plugin skills named ai-agents-skills:agent-<name> (for example,
skill_view("ai-agents-skills:agent-log-investigator")).

Install (Claude Code)

As a marketplace from this repo:

/plugin marketplace add Xakki/ai-agents-skills
/plugin install ai-agents-skills@ai-agents-skills

Dependency: mempalace

This plugin declares a dependency on the mempalace
plugin (cross-marketplace). Claude Code resolves a dependency only from a
marketplace you have already added — so add the mempalace marketplace before
installing, otherwise the install fails with dependency-unsatisfied:

/plugin marketplace add MemPalace/mempalace
/plugin marketplace add Xakki/ai-agents-skills
/plugin install ai-agents-skills@ai-agents-skills

With the mempalace marketplace present, installing ai-agents-skills pulls in
mempalace automatically.

Or from a local checkout:

/plugin marketplace add /home/xakki/ai-agents-skills
/plugin install ai-agents-skills@ai-agents-skills

Verify the manifest and skill frontmatter at any time:

claude plugin validate /home/xakki/ai-agents-skills

Install (Codex)

1. Install Codex CLI. The standalone installer is preferred on Linux (no
   Node.js/Homebrew dependency):

   curl -fsSL https://chatgpt.com/codex/install.sh | sh
   

2. Add this repo as a Codex plugin marketplace:

   codex plugin marketplace add Xakki/ai-agents-skills
   

3. Launch codex, open the plugin picker, and install/enable
   ai-agents-skills:

   /plugins
   

4. Start a new Codex session — plugin skills and hooks are loaded at
   session start, so an existing session won't pick them up.

Codex loads hooks from the path declared in .codex-plugin/plugin.json
(./hooks/codex-hooks.json), not from hooks/hooks.json (that file is
Claude Code–only). Plugin-bundled hooks are non-managed, so on first run
Codex prompts you to review and trust them before they execute.

Verify the Codex install

codex plugin marketplace list   # confirms the Xakki/ai-agents-skills source is registered
codex plugin list               # confirms ai-agents-skills is installed/enabled
/plugins                        # same, from inside a Codex session

Note: the mempalace cross-marketplace dependency declared in
.claude-plugin/plugin.json is Claude Code–specific; install
mempalace separately as a Codex
plugin if you want it there too.

Install (Hermes)

Install and explicitly enable the plugin from GitHub:

hermes plugins install Xakki/ai-agents-skills --enable

For a local Git checkout, use a file:// Git URL (the installer clones the
repository, so uncommitted working-tree changes are not included):

hermes plugins install file:///path/to/ai-agents-skills --enable

Verify discovery and state:

hermes plugins list --plain --no-bundled

Hermes registers all skills/*/SKILL.md files read-only under
ai-agents-skills:<name> and all agents/*.md prompts under
ai-agents-skills:agent-<name>. Plugin skills are intentionally namespaced and
opt-in in Hermes, so load one explicitly, for example:

skill_view("ai-agents-skills:qa-check")
skill_view("ai-agents-skills:agent-db-schema")

The Hermes adapter maps pre_llm_call, post_llm_call, session-finalize, and
session-reset events to the shared abbreviation and Telegram hook behavior.
Hermes does not expose a plugin hook for permission/idle notifications, so that
specific Telegram ping is not wired. schedule-tasks and setup-claude remain
Claude-specific workflows; model-tiers is informational under Hermes because
Hermes subagents inherit the active model rather than accepting a per-call tier.
The mempalace dependency in the Claude manifest is not installed by Hermes.

Install (Cursor)

1. Install the Cursor Agent CLI (cursor-agent).

2. Register this repo as a plugin marketplace source:

   cursor-agent plugin marketplace add https://github.com/Xakki/ai-agents-skills
   

3. As of this writing, the Cursor CLI has no non-interactive plugin install command (confirmed against cursor-agent plugin --help and
   Cursor's own docs/forum, 2026-07-31) — plugin marketplace add only
   registers the source. Enable the plugin one of these ways:

   • Interactive CLI: run cursor-agent, type /plugin, open the
     Marketplace tab, select ai-agents-skills, and press Enter —
     choose user scope to make it available in every future session, or
     project scope for just this repo.

   • Cursor IDE: open Customize in the sidebar → Plugins → find
     ai-agents-skills → install.

   • Local/dev testing (no marketplace registration needed): point the
     CLI directly at a checkout of this repo:

     cursor-agent --plugin-dir /path/to/ai-agents-skills
     

4. Verify:

   cursor-agent plugin marketplace list   # confirms the source is registered
   

   In a fresh session, confirm the skills (skills/), the 3 agents
   (agents/*.md), and the 5 Cursor hook bindings from
   hooks/cursor-hooks.json are discoverable — the Hooks tab and
   Customize panel in Cursor list configured/executed hooks and
   installed skills/agents.

Cursor loads this plugin's skills, agents, and hooks through
hooks/cursor-hooks.json (routed through a normalization adapter,
hooks/cursor-adapter.sh, since Cursor's hook payload field names differ
from Claude Code's/Codex's). Session-start context injection, prompt-start
bookkeeping, and the "✅ task finished" Telegram ping all work the same as
under Claude Code/Codex. The "🔐 needs your permission" / "⏰ waiting for
input" ping does not fire under Cursor — there is no Cursor hook event
for it. See the design doc
for why.

Note: the mempalace cross-marketplace dependency declared in
.claude-plugin/plugin.json is Claude Code–specific; install
mempalace separately for Cursor if
you want it there too.

Layout

.
├── .claude-plugin/
│   ├── plugin.json        # Claude Code plugin manifest (only this file lives here)
│   └── marketplace.json   # marketplace entry → source "./" (also read by Codex, legacy-compatible)
├── .codex-plugin/
│   └── plugin.json        # Codex plugin manifest (only this file lives here)
├── .cursor-plugin/
│   ├── plugin.json        # Cursor plugin manifest — declares "hooks": "./hooks/cursor-hooks.json"
│   └── marketplace.json   # marketplace entry → source "./"
├── plugin.yaml             # Hermes plugin manifest
├── __init__.py             # Hermes skill + lifecycle-hook registration adapter
├── after-install.md        # Hermes post-install usage summary
├── AGENTS.md              # Codex instructions: shared skills/, separate hook maps
├── hooks/
│   ├── hooks.json         # Claude Code hooks (auto-registered, 6 events)
│   ├── codex-hooks.json   # same hooks mapped to Codex's event names (see plugin.json → "hooks")
│   ├── cursor-hooks.json  # same hooks mapped to Cursor's event names, via cursor-adapter.sh
│   ├── cursor-adapter.sh  # normalizes Cursor payloads for the shared tg-*.sh / abbr-inject.sh scripts
│   └── tg-*.sh
├── skills/
│   ├── kanban/
│   ├── schedule-tasks/
│   ├── tg-notify/         # SKILL.md + tg-notify.sh + runtime/context helpers + .env.example
│   ├── tg-notify-timers/
│   ├── tg-report/         # completion/task reports → tg-notify, topics from env
│   ├── git-flow/          # shared git core (commit/branch/PR conventions)
│   ├── git-move/
│   ├── setup-claude/
│   ├── new-project-docker/
│   └── fluent-logging/
└── scripts/               # runners used by schedule-tasks (run from the plugin cache)

For Claude Code, the skills are auto-discovered from skills/, and the hooks
from hooks/hooks.json — no skills or hooks field in
.claude-plugin/plugin.json is needed. The Codex manifest
(.codex-plugin/plugin.json) declares both explicitly: "skills": "./skills/"
and "hooks": "./hooks/codex-hooks.json", so Codex loads the same skills but
its own hook map instead of hooks/hooks.json. The Cursor manifest
(.cursor-plugin/plugin.json) auto-discovers skills/ and agents/ the same
way Claude Code does (default folder-based discovery), and declares hooks
explicitly (same posture as Codex) pointing at ./hooks/cursor-hooks.json —
the adapted event map that routes through hooks/cursor-adapter.sh.
Hermes loads the root plugin.yaml and __init__.py; the adapter registers the
same skill files without copying them and normalizes Hermes lifecycle callback
arguments for the shared Telegram scripts.

Usage

• kanban triggers on task-management requests ("create a task", "what's in
  progress", "mark done"). It operates on .claude/kanban/ in your current
  project; the board is created on first use.
• schedule-tasks triggers on "schedule tasks" / "запланируй задачи". It needs
  atd active and a byobu/tmux session, and reads cards from
  .claude/kanban/todo/ in your current project.
• tg-notify triggers on "send to telegram" / "notify in TG" / "ping me when
  done", and auto-sends via its hooks for long task completion and
  permission/idle prompts. See tg-notify for setup.

schedule-tasks & the plugin cache

schedule-tasks invokes the runner scripts from ${CLAUDE_PLUGIN_ROOT}/scripts/
(the installed plugin's cache), not from your repo. The scripts derive the
target repo from the task-file path they're given
(<repo>/.claude/kanban/<stage>/<name>.md), so they work from any project
without per-repo configuration. Your kanban board still lives in your project
under .claude/kanban/.

tg-notify

The bot token and destination come from the environment — nothing secret is
committed. Configure once, then both the manual sender and the hooks use it.

1. Create a bot with @BotFather and copy its token.

2. Copy the template and fill it in (chmod 600):

   mkdir -p ~/.config/tg-notify
   ROOT="${AI_AGENTS_SKILLS_ROOT:-${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}}}"
   cp "$ROOT/skills/tg-notify/.env.example" ~/.config/tg-notify/.env
   chmod 600 ~/.config/tg-notify/.env
   $EDITOR ~/.config/tg-notify/.env
   

   (Exported env vars TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / … override the file.)

3. Choose the destination with TELEGRAM_CHAT_ID — this is the single switch
   between a private chat, a group, and a channel:

   Destination	TELEGRAM_CHAT_ID	Notes
   Private chat (DM)	numeric user id, e.g. 123456789	start a chat with the bot first
   Group / supergroup	negative id, e.g. -1001234567890	add the bot to the group; set TELEGRAM_THREAD_ID for a forum topic
   Channel	-100… id or @username	add the bot as an admin

Two destinations: DM hooks vs. report group

tg-notify (and its hooks) use TELEGRAM_CHAT_ID — typically your DM, so
"task finished / needs attention" pings reach you privately. The tg-report
skill sends explicit, on-request reports to a separate TELEGRAM_NOTIFY_*
destination — a group with topics:

Keep these out of TELEGRAM_CHAT_ID — topics need a group, and the DM is for the
hooks. For a single user, the TELEGRAM_NOTIFY_* vars sit nicely in
~/.claude/settings.json (env block); the bot token stays in the chmod-600
creds file. If tg-report finds a required value unset, it asks rather than
sending blind.

The hooks fire on these events (auto-registered from hooks/hooks.json):

Under Cursor, the same four scripts fire via
sessionStart/beforeSubmitPrompt/preToolUse/stop/sessionEnd through
hooks/cursor-adapter.sh; there is no Cursor equivalent of Notification,
so the permission/idle ping does not fire there.

Under Hermes, pre_llm_call records prompt start and injects abbreviations on
the first turn; post_llm_call supplies the final response directly to
tg-on-stop.sh; session finalize/reset cancels stale pending notices. Hermes
has no permission/idle hook, so that notice is intentionally omitted.

Each notice is scheduled with a delay and cancelled if you become active before
it fires, so you only get pinged when you've genuinely stepped away. Thresholds and
delays are overridable via env (TG_NOTIFY_STOP_THRESHOLD, TG_NOTIFY_DELAY, …).
State, logs, and undelivered payloads live under $TG_NOTIFY_HOME
(default $CLAUDE_PLUGIN_DATA, else ~/.local/state/tg-notify).

Requirements

• schedule-tasks: atd running (systemctl is-active atd), at/atq/atrm,
  a tmux/byobu session, and claude on PATH.
• tg-notify: curl, jq, python3, and (for the context header in hooks) a
  tmux/byobu session. A TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID as above.

Recommendation skills

• impeccable (for landings) npx -y skills add pbakaus/impeccable --skill impeccable --agent claude-code -g
• task observer npx -y skills add rebelytics/one-skill-to-rule-them-all --skill task-observer --agent claude-code -g

Contributing — when to migrate a skill here

A debugged, universal skill / agent / rule belongs in this plugin. Criteria:
it works correctly and carries no personal data. Parameterize it via env/config
following the tg-notify pattern:

• secrets in ~/.config/<tool>/.env (chmod 600) + a placeholder .env.example in git;
• the skill body references env vars only — no hardcoded chat ids, threads, tokens,
  host paths, or other users' paths;
• in-repo paths use AI_AGENTS_SKILLS_ROOT with the runtime-specific
  CLAUDE_PLUGIN_ROOT / PLUGIN_ROOT / CURSOR_PLUGIN_ROOT fallbacks, never a
  hardcoded checkout path.

After moving a skill: commit + push → force a plugin update → verify the new
gitCommitSha (auto-update keys off the SHA, not the manifest version) → only
then delete the local duplicate from ~/.claude/skills/. Host-/secret-/project-
specific material stays local.

License

MIT — see LICENSE.