agent-signal
- Repo stars 77,599
- Author updated Live
- Author repo lobehub
- Domain
- AI
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @lobehub · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools，默认拥有全部工具权限。
---
name: agent-signal
description: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by even…
category: ai
runtime: Node.js
---
# agent-signal output preview
## PART A: Task fit
- Use case: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic signals, and action handlers. Use when adding a new Agent Signal source, signal or action type, policy, middleware handler, workflow handoff, dedupe or scope behavior, or observability around `src/server/services/agentSignal/**`, `packages/agent-signal`, or `packages/observability-otel/src/modules/agent-signal`..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Start Here / Use The Right Entry Point / Core Model” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic signals, and action handlers. Use when adding a new Agent Signal source, signal or action type, policy, middleware handler, workflow handoff, dedupe or scope behavior, or observability around `src/server/services/agentSignal/**`, `packages/agent-signal`, or `packages/observability-otel/src/modules/agent-signal`.”.
- **02** When the source has headings, the agent prioritizes “Start Here / Use The Right Entry Point / Core Model” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. Choose the trigger
The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Provide inputs and boundaries
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Validate with a small run
Start with a small task and check whether the result follows “Start Here / Use The Right Entry Point / Core Model”. Inspect diffs, logs, previews, or tests before expanding scope.
Review before delivery
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: agent-signal
description: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by even…
category: ai
source: lobehub/lobehub
---
# agent-signal
## When to use
- Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic si…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Start Here / Use The Right Entry Point / Core Model” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. Evidence boundary and execution chain
The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "agent-signal" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Start Here / Use The Right Entry Point / Core Model
rules -> SKILL.md triggers / order / output contract
runtime -> Node.js | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
}Agent Signal
Use this skill to implement event-driven background work for agents without coupling the work to the foreground chat request.
Agent Signal has one consistent shape:
source event -> signal interpretation -> action execution -> built-in result signals
Start Here
- Read
references/architecture.mdto map the package boundary, runtime queue, scope model, and async workflow handoff. - Read
references/handlers.mdbefore writing any new policy, source handler, signal handler, or action handler. - Read
references/observability.mdwhen you need tracing, metrics, debugging, or workflow snapshot visibility.
Use The Right Entry Point
- Use
emitAgentSignalSourceEvent(...)when a server-owned producer should execute the pipeline immediately. - Use
executeAgentSignalSourceEvent(...)when a worker or controlled backend path already owns execution timing and may inject a runtime guard backend. - Use
enqueueAgentSignalSourceEvent(...)when the caller should return quickly and let Upstash Workflow process the event out-of-band. - Use
emitAgentSignalSourceEventWithStore(...)for isolated tests or evals that should avoid ambient Redis state.
Read:
src/server/services/agentSignal/index.tssrc/server/workflows/agentSignal/index.tssrc/server/workflows/agentSignal/run.ts
Core Model
source: A normalized fact that happened. Sources come from producers such as runtime lifecycle events, user messages, or bot ingress.signal: A semantic interpretation derived from one source or from another signal. Signals express meaning, routing, or policy state.action: A concrete side effect planned from one signal. Actions do the work.policy: An installable middleware bundle that registers source, signal, and action handlers.procedure: Not a distinct runtime node. Treat "procedure" as the end-to-end flow for one use case: ingress source, matching handlers, planned actions, execution result, and observability.
Keep the boundaries strict:
- Add a new
sourcewhen the outside world produced a new event. - Add a new
signalwhen the system needs a reusable semantic interpretation. - Add a new
actionwhen the runtime needs a concrete side effect. - Add or update a
policywhen you are wiring those pieces together.
Implementation Workflow
- Decide whether the use case is synchronous or quiet background work.
- Define or reuse a source type in
src/server/services/agentSignal/sourceTypes.ts. - Define or reuse signal and action types in
src/server/services/agentSignal/policies/types.ts. - Implement handlers with
defineSourceHandler,defineSignalHandler, ordefineActionHandler. - Bundle handlers with
defineAgentSignalHandlers(...). - Register the policy in
src/server/services/agentSignal/policies/index.tsand pass it into the runtime factory if needed. - Add or update ingress code that emits or enqueues the source event.
- Add observability and tests before considering the flow complete.
Default Reading Set
- Shared semantic core:
packages/agent-signal/src/index.tspackages/agent-signal/src/base/builders.tspackages/agent-signal/src/base/types.ts - Server-owned runtime and middleware:
src/server/services/agentSignal/runtime/AgentSignalRuntime.tssrc/server/services/agentSignal/runtime/AgentSignalScheduler.tssrc/server/services/agentSignal/runtime/middleware.tssrc/server/services/agentSignal/runtime/context.ts - Existing policy example:
src/server/services/agentSignal/policies/analyzeIntent/index.tssrc/server/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.tssrc/server/services/agentSignal/policies/analyzeIntent/feedbackDomain.tssrc/server/services/agentSignal/policies/analyzeIntent/feedbackAction.tssrc/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts - Observability:
src/server/services/agentSignal/observability/projector.tssrc/server/services/agentSignal/observability/traceEvents.tspackages/observability-otel/src/modules/agent-signal/index.ts
Implementation Rules
- Reuse existing source, signal, and action types before adding new ones.
- Keep source handlers focused on interpretation and fan-out, not heavy side effects.
- Keep action handlers responsible for side effects, idempotency, and executor-style result reporting.
- Use stable ids and idempotency keys when the same source can arrive more than once.
- Preserve scope discipline. The runtime uses
scopeKeyto serialize related background work. - Prefer the dedicated shared package types and builders from
@lobechat/agent-signalfor normalized nodes and result contracts. - Add focused tests near the touched runtime, policy, or store module. Existing tests under
src/server/services/agentSignal/**/__tests__are the reference pattern.
References
- Architecture and boundaries:
references/architecture.md - Writing handlers and policies:
references/handlers.md - Observability, metrics, and debugging:
references/observability.md
Decide Fit First
Design Intent
How To Use It
Boundaries And Review