agent-kernel
Skill5 starsChanged 4 months agoMITView on GitHub
Local-first governance, memory, runtime evidence, project isolation, architecture conformance, and release safety for AI coding agents. Use Agent Kernel when a user wants Claude Code, Codex, Cursor, OpenCode, Antigravity, Gemini CLI, or AGENTS.md-compatible agents to share persistent rules, reviewed workflows, Failure Lessons, episodes, bounded runtime context, project connection manifests, provider approvals, generated guidance, MCP tools, hooks, command guards, or architecture contracts. Strong triggers include: remember this rule, make every coding agent follow this workflow, capture this recurring failure, search previous debugging evidence, prevent architecture drift, search before creating a service, connect this repository safely, configure local MCP, secure the runtime daemon, inspect project provider boundaries, or prepare and verify an Agent Kernel release.
- Reads credentials
- Installs packages
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .codex/AGENTS.mdAGENTS.md
- agent-kernelSkill
- architecture-guardianSkill
- agent-kernelSkill
- architecture-guardianSkill
- agent-kernel-evolveSkill
- agent-kernel-opsSkill
- architecture-guardianSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
28 rules. About 0 are common, 22 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈22
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 22
Use this skill when the task requires one or more of these capabilities:
- Distinctive: line 35
verify Agent Kernel CI, package, documentation, or release integrity
- Distinctive: line 37
Do not activate it for a generic coding task when the user does not need persistent governance, memory, runtime evidence, project …
- Very specific: line 86
Use agent-kernel link . --hooks only when the main linker is intentionally preferred over managed-block preservation.
- Distinctive: line 120
Do not construct session paths manually.
- Distinctive: line 166
When the user explicitly states a durable rule and asks to save it, direct approved memory is appropriate:
- Very specific: line 192
Use --strict only when the project policy, baseline, contract, and active exceptions are reviewed.
- Distinctive: line 212
Never print, summarize, diff, or paste vault file contents
- Very specific: line 213
Read docs/ENVIRONMENT_VAULT.md before a forced overwrite or purge
- Very specific: line 214
Do not use --force unless the user understands a differing local file will be replaced
- Distinctive: line 259
Use project connection when a repository needs shared global memory but isolated local configuration and provider targets.
- Distinctive: line 286
Do not add credentials to project manifests.
- Distinctive: line 349
Default to approval mode. Use trusted or bypass only when the user deliberately accepts the broader write behavior.
- Distinctive: line 383
all version surfaces agree
- Distinctive: line 385
all smoke tests pass on supported Node versions
- Very specific: line 391
After tagging, verify npm registry visibility, package integrity, GitHub Release assets, and SHA256SUMS.
- Distinctive: line 395
Use the canonical reference for the complete surface:
- Distinctive: line 399
search, context, sessions, episodes, and failures
- Distinctive: line 422
Do not claim native blocking hooks for an agent unless Agent Kernel ships and tests that adapter.
- Distinctive: line 426
Read current project instructions before changing files.
- Distinctive: line 427
Search memory and Failure Lessons before repeating known work.
- Distinctive: line 428
Use bounded context rather than loading the entire local store.
- Distinctive: line 429
Keep durable memory proposal-first unless the user explicitly approves direct storage.
- Very specific: line 430
Never store secrets, .env values, provider tokens, service-account files, or auth material in memory or project manifests.
- Distinctive: line 431
Use safe-link and dry-run before editing existing guidance or hooks.
- Distinctive: line 432
Treat remote daemon mode, MCP approval, bypass mode, strict architecture enforcement, production provider approvals, and replacement …
- Distinctive: line 433
Run targeted tests first, then the full release or repository gate required by the change.
- Distinctive: line 434
Update runtime docs, skill docs, discovery metadata, and regression checks together when behavior changes.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Kernel
Agent Kernel is a local-first governance layer for coding agents. It does not replace the agent. It gives multiple agents one reviewed source of truth for durable memory, failure evidence, project boundaries, architecture policy, and release discipline.
Activate this skill when
Use this skill when the task requires one or more of these capabilities:
- save a durable user rule, preference, workflow, policy, project note, or skill trigger
- let an agent propose memory without approving it
- capture and search repeated build, test, command, or edit failures
- retrieve bounded task or file context from local approved state
- record sessions, observations, timelines, episodes, or commit evidence
- connect a project without duplicating the global runtime or overwriting user instructions
- isolate provider profiles, environments, project targets, and production approvals
- prevent architecture drift, duplicate capabilities, cycles, or out-of-scope writes
- install or inspect generated agent guidance, hooks, MCP, guard rules, or safe linking
- inspect or secure the optional HTTP daemon
- back up, import, compact, report, or review local state
- verify Agent Kernel CI, package, documentation, or release integrity
Do not activate it for a generic coding task when the user does not need persistent governance, memory, runtime evidence, project connection, or architecture conformance.
Core mental model
user intent
-> agent reads approved guidance and bounded context
-> agent works inside project and architecture scope
-> failures and useful evidence are captured locally
-> durable changes become pending proposals
-> user reviews and approves
-> Agent Kernel publishes generated guidance
-> future agents inherit the reviewed resultNon-negotiable trust boundaries
- Approved source memory is canonical. Generated
AGENTS.md,CLAUDE.md, Cursor rules, Gemini guidance, and other compiled files are delivery outputs. - Agents may capture and propose. They must not silently approve or publish durable memory.
- Failure Lessons are evidence. Promotion creates a pending proposal.
- Session, proposal, episode, commit-link, and other file-backed IDs are identifiers, not filesystem paths.
- The daemon is optional and local-only by default. Remote mode requires explicit opt-in and a bearer token of at least 32 bytes.
- MCP defaults to a bounded core surface. Approval is disabled by default. Publish and delete are never exposed through MCP.
- Existing project instructions are user-owned. Use safe-link and dry-run before changing them.
- Project provider targets come from reviewed manifests. Caller overrides must not replace project, region, account, configuration, or project reference.
- Architecture policy, baselines, contracts, and exceptions require review. Do not broaden them silently.
- A release is not complete until the package, GitHub tag, npm registry, provenance path, release assets, and checksums are verified.
Fast setup
npm install -g @mamdouh-aboammar/agent-kernel
agent-kernel --version
agent-kernel init --sync
agent-kernel doctorFor an existing repository:
cd /path/to/project
agent-kernel compile
agent-kernel-safe-link . --dry-run
agent-kernel-safe-link .
agent-kernel-safe-git-hook . --dry-run
agent-kernel-safe-git-hook .
agent-kernel doctorUse agent-kernel link . --hooks only when the main linker is intentionally preferred over managed-block preservation.
Operating loop
1. Inspect before writing
agent-kernel doctor
agent-kernel status
agent-kernel search "<task or error>" --explain
agent-kernel context "<task>" --files src/example.mjs --budget 1200For a connected project:
agent-kernel project status --json
agent-kernel context current --json2. Start a bounded session when evidence matters
agent-kernel session start --agent codex --project . --json
agent-kernel session observe <session-id> \
--type command \
--command "npm test" \
--exit-code 0 \
--text "Focused tests passed" \
--file test/example.mjs
agent-kernel session timeline <session-id> --compact
agent-kernel session end <session-id>Do not construct session paths manually. Pass only the ID returned by Agent Kernel.
3. Search Failure Lessons before retrying
agent-kernel failure search "ERR_MODULE_NOT_FOUND"Capture reusable failure evidence:
agent-kernel failure capture \
--from codex \
--type test-failure \
--command "npm test" \
--exit-code 1 \
--text "<redacted error output>" \
--root-cause "<supported root cause>" \
--fix "<smallest verified fix>"Promote only after the pattern is reusable:
agent-kernel failure propose <failure-id> --as rule
agent-kernel inbox4. Propose durable memory
agent-kernel propose \
--from codex \
--text "Use pnpm in this repository." \
--reason "The user corrected the package manager during setup."The normal user review path is:
agent-kernel inbox
agent-kernel approve <proposal-id> --publish
# or
agent-kernel reject <proposal-id>When the user explicitly states a durable rule and asks to save it, direct approved memory is appropriate:
agent-kernel remember "Never commit provider credentials." \
--type policy \
--level critical \
--publish5. Keep architecture changes bounded
Load the dedicated Architecture Guardian skill before a non-trivial feature, refactor, cross-module fix, new service, new dependency, schema change, or public API change.
agent-kernel architecture doctor .
agent-kernel architecture discover . --json
agent-kernel architecture reuse "<capability>" . --json
agent-kernel architecture contract init . \
--task "<reviewed task>" \
--owner "<domain or team>" \
--allow "src/area/**,test/area/**" \
--expect "src/area/file.ts,test/area/file.test.ts" \
--tests "<observable behavior>"
agent-kernel architecture check . --jsonUse --strict only when the project policy, baseline, contract, and active exceptions are reviewed.
6. Link evidence to Git when useful
agent-kernel commit link \
--sha <commit-sha> \
--session <session-id> \
--failure <failure-id> \
--files src/example.mjs,test/example.mjs
agent-kernel commit context <commit-sha> --jsonEnvironment Vault
Environment Vault stores selected project .env files locally under the configured Agent Kernel home. It uses a full SHA256 project fingerprint so fresh clones, SSH and HTTPS remotes, and Monorepos all resolve to one identity.
Safety rules before any vault command:
- Never print, summarize, diff, or paste vault file contents
- Read
docs/ENVIRONMENT_VAULT.mdbefore a forced overwrite or purge - Do not use
--forceunless the user understands a differing local file will be replaced
Quick workflow:
# Link project and discover eligible .env files
agent-kernel env link [project] [--include path] [--exclude pattern]
# Check identity, health, and file states
agent-kernel env status [project] --json
# Store changed local files
agent-kernel env push [project] [--file path] [--dry-run]
# Restore missing files (never overwrites existing without --force)
agent-kernel env pull [project] [--file path] [--force]
# Watch for changes in the background
agent-kernel env watch [project]
# Inspect revision history (no secret content)
agent-kernel env history [project] --file .env
# Restore a specific revision
agent-kernel env restore [project] --file .env --revision <id>
# Run health checks and repair permissions
agent-kernel env doctor [project] [--repair-permissions] [--migrate]
# List all local vault identities
agent-kernel env list --json
# Detach project path while keeping stored files
agent-kernel env unlink [project]
# Delete stored data (requires explicit --yes)
agent-kernel env purge [project] --yesVault directories use 0700 and stored files use 0600 on POSIX systems.
See docs/ENVIRONMENT_VAULT.md for discovery rules, monorepo support, migration, conflict handling, and threat boundaries.
Project Context Broker
Use project connection when a repository needs shared global memory but isolated local configuration and provider targets.
agent-kernel project connect --dry-run
agent-kernel project connect --yes
agent-kernel project status --json
agent-kernel project doctorValidated project/environment context:
agent-kernel context enter <project-id> development --json
agent-kernel context current --jsonProduction provider operations require a matching short-lived approval:
agent-kernel approvals request \
--provider gcloud \
--operation deploy \
--reason "Reviewed deployment window"
agent-kernel approvals approve <approval-id> --ttl-minutes 15
agent-kernel provider gcloud exec -- run deploy <service>Do not add credentials to project manifests. Persistent credentials use the supported secure platform backend. Process environment credentials remain process-scoped and must not be logged.
Optional daemon
Local mode:
agent-kernel daemon start
agent-kernel daemon status --json
agent-kernel daemon stopRemote mode is a separate security decision:
export AGENT_KERNEL_DAEMON_HOST=0.0.0.0
export AGENT_KERNEL_DAEMON_ALLOW_REMOTE=1
export AGENT_KERNEL_DAEMON_TOKEN="$(openssl rand -hex 32)"
agent-kernel daemon startRemote requests require Authorization: Bearer <token>. Use a private network or authenticated tunnel. Never expose the port directly to the public internet.
MCP
Inspect the default surface:
agent-kernel mcp testCore mode exposes ten tools for status, memory search, bounded context, proposals, guard checks, Failure Lessons, and episode search.
Extended mode is explicit:
AGENT_KERNEL_MCP_TOOLS=extended agent-kernel mcp testApproval requires both extended mode and AGENT_KERNEL_MCP_ALLOW_APPROVE=1. Prefer terminal review even when explicit MCP approval is available.
Memory write mode and agent identity
These are separate controls.
Global write mode:
agent-kernel-mode show
agent-kernel-mode set approval
agent-kernel-mode set trusted
agent-kernel-mode set bypassAgent identity trust:
agent-kernel agent list --json
agent-kernel agent add codex --trust propose-only --surface cli
agent-kernel agent set codex --trust capture-only
agent-kernel agent show codex --jsonDefault to approval mode. Use trusted or bypass only when the user deliberately accepts the broader write behavior.
Portability and local reports
agent-kernel retention status --json
agent-kernel export ./agent-kernel-backup.json --redact --include-observations
agent-kernel import ./agent-kernel-backup.json --inspect --json
agent-kernel dashboard --no-open --json
agent-kernel report ./agent-kernel-report.html --jsonInspect before import. Do not commit raw exports or reports that may contain project evidence.
Update and release discipline
User-side update flow:
agent-kernel update status --json
agent-kernel update check --force --json
agent-kernel update apply --agent <trusted-agent-id> --jsonRepository release flow:
npm ci
npm run verify:release
npm run publish:dryBefore tagging, verify:
- all version surfaces agree
- docs links and docs contracts pass
- all smoke tests pass on supported Node versions
- Windows CI and CodeQL pass
- the target npm version is not already published
- the tag exactly matches
package.json - release workflows load successfully
After tagging, verify npm registry visibility, package integrity, GitHub Release assets, and SHA256SUMS.
Command families
Use the canonical reference for the complete surface:
- core memory and guidance
- Environment Vault — secure
.envstorage, versioned revisions, conflict-safe restore - search, context, sessions, episodes, and failures
- Architecture Guardian
- guards, linking, hooks, and MCP
- project connection, provider approvals, and audit
- agent and project identity registries
- commit evidence
- retention, export, import, dashboard, and reports
- updates and releases
See docs/COMMAND_REFERENCE.md.
Agent compatibility
| Agent | Primary integration |
| Claude Code | CLAUDE.md, AGENTS.md, local MCP, narrow hooks, Claude skills |
| Codex | AGENTS.md, .codex/AGENTS.md, .codex/config.toml, .agents/skills/ |
| Cursor | .cursor/rules/00-agent-kernel.mdc, local MCP |
| OpenCode | AGENTS.md, local MCP |
| Antigravity | .agents/agents.md, .agents/skills/ |
| Gemini CLI | GEMINI.md, local MCP configuration |
| AGENTS.md-compatible tools | AGENTS.md and the AGENTS-compatible skill |
Do not claim native blocking hooks for an agent unless Agent Kernel ships and tests that adapter.
Rules for agents using this skill
- Read current project instructions before changing files.
- Search memory and Failure Lessons before repeating known work.
- Use bounded context rather than loading the entire local store.
- Keep durable memory proposal-first unless the user explicitly approves direct storage.
- Never store secrets,
.envvalues, provider tokens, service-account files, or auth material in memory or project manifests. - Use safe-link and dry-run before editing existing guidance or hooks.
- Treat remote daemon mode, MCP approval, bypass mode, strict architecture enforcement, production provider approvals, and replacement imports as separate explicit decisions.
- Run targeted tests first, then the full release or repository gate required by the change.
- Update runtime docs, skill docs, discovery metadata, and regression checks together when behavior changes.
Canonical documentation
- Documentation map
- Command reference
- Environment Vault
- Environment variables
- Install and agent setup
- Troubleshooting
- Operating model
- AI agent runbook
- MCP server
- Project connection
- Architecture Guardian
- Secure runtime and releases
- Skill contract
Discovery
npx skills add imMamdouhaboammar/agent-kernel -a claude-code -g -y
npm install -g @mamdouh-aboammar/agent-kernelDiscovery surfaces:
SKILL.md
skills.sh.json
skills/architecture-guardian/SKILL.md
.claude/skills/agent-kernel/SKILL.md
.claude/skills/architecture-guardian/SKILL.md
.agents/skills/agent-kernel/SKILL.md
.agents/skills/architecture-guardian/SKILL.md
.claude-plugin/marketplace.json
.claude-plugin/plugin.jsonLicense
MIT © Mamdouh Aboammar
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

