agentleFS
imMamdouhaboammarimMamdouhaboammar/agent-kernel/SKILL.md

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

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
  1. Distinctive:

    Use this skill when the task requires one or more of these capabilities:

    line 22
  2. Distinctive:

    verify Agent Kernel CI, package, documentation, or release integrity

    line 35
  3. Distinctive:

    Do not activate it for a generic coding task when the user does not need persistent governance, memory, runtime evidence, project …

    line 37
  4. Very specific:

    Use agent-kernel link . --hooks only when the main linker is intentionally preferred over managed-block preservation.

    line 86
  5. Distinctive:

    Do not construct session paths manually.

    line 120
  6. Distinctive:

    When the user explicitly states a durable rule and asks to save it, direct approved memory is appropriate:

    line 166
  7. Very specific:

    Use --strict only when the project policy, baseline, contract, and active exceptions are reviewed.

    line 192
  8. Distinctive:

    Never print, summarize, diff, or paste vault file contents

    line 212
  9. Very specific:

    Read docs/ENVIRONMENT_VAULT.md before a forced overwrite or purge

    line 213
  10. Very specific:

    Do not use --force unless the user understands a differing local file will be replaced

    line 214
  11. Distinctive:

    Use project connection when a repository needs shared global memory but isolated local configuration and provider targets.

    line 259
  12. Distinctive:

    Do not add credentials to project manifests.

    line 286
  13. Distinctive:

    Default to approval mode. Use trusted or bypass only when the user deliberately accepts the broader write behavior.

    line 349
  14. Distinctive:

    all version surfaces agree

    line 383
  15. Distinctive:

    all smoke tests pass on supported Node versions

    line 385
  16. Very specific:

    After tagging, verify npm registry visibility, package integrity, GitHub Release assets, and SHA256SUMS.

    line 391
  17. Distinctive:

    Use the canonical reference for the complete surface:

    line 395
  18. Distinctive:

    search, context, sessions, episodes, and failures

    line 399
  19. Distinctive:

    Do not claim native blocking hooks for an agent unless Agent Kernel ships and tests that adapter.

    line 422
  20. Distinctive:

    Read current project instructions before changing files.

    line 426
  21. Distinctive:

    Search memory and Failure Lessons before repeating known work.

    line 427
  22. Distinctive:

    Use bounded context rather than loading the entire local store.

    line 428
  23. Distinctive:

    Keep durable memory proposal-first unless the user explicitly approves direct storage.

    line 429
  24. Very specific:

    Never store secrets, .env values, provider tokens, service-account files, or auth material in memory or project manifests.

    line 430
  25. Distinctive:

    Use safe-link and dry-run before editing existing guidance or hooks.

    line 431
  26. Distinctive:

    Treat remote daemon mode, MCP approval, bypass mode, strict architecture enforcement, production provider approvals, and replacement …

    line 432
  27. Distinctive:

    Run targeted tests first, then the full release or repository gate required by the change.

    line 433
  28. Distinctive:

    Update runtime docs, skill docs, discovery metadata, and regression checks together when behavior changes.

    line 434

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 result

Non-negotiable trust boundaries

  1. Approved source memory is canonical. Generated AGENTS.md, CLAUDE.md, Cursor rules, Gemini guidance, and other compiled files are delivery outputs.
  2. Agents may capture and propose. They must not silently approve or publish durable memory.
  3. Failure Lessons are evidence. Promotion creates a pending proposal.
  4. Session, proposal, episode, commit-link, and other file-backed IDs are identifiers, not filesystem paths.
  5. The daemon is optional and local-only by default. Remote mode requires explicit opt-in and a bearer token of at least 32 bytes.
  6. MCP defaults to a bounded core surface. Approval is disabled by default. Publish and delete are never exposed through MCP.
  7. Existing project instructions are user-owned. Use safe-link and dry-run before changing them.
  8. Project provider targets come from reviewed manifests. Caller overrides must not replace project, region, account, configuration, or project reference.
  9. Architecture policy, baselines, contracts, and exceptions require review. Do not broaden them silently.
  10. 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 doctor

For 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 doctor

Use 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 1200

For a connected project:

agent-kernel project status --json
agent-kernel context current --json

2. 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 inbox

4. 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 \
  --publish

5. 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 . --json

Use --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> --json

Environment 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.md before a forced overwrite or purge
  • Do not use --force unless 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] --yes

Vault 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 doctor

Validated project/environment context:

agent-kernel context enter <project-id> development --json
agent-kernel context current --json

Production 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 stop

Remote 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 start

Remote 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 test

Core 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 test

Approval 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 bypass

Agent 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 --json

Default 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 --json

Inspect 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> --json

Repository release flow:

npm ci
npm run verify:release
npm run publish:dry

Before 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 .env storage, 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

AgentPrimary integration
Claude CodeCLAUDE.md, AGENTS.md, local MCP, narrow hooks, Claude skills
CodexAGENTS.md, .codex/AGENTS.md, .codex/config.toml, .agents/skills/
Cursor.cursor/rules/00-agent-kernel.mdc, local MCP
OpenCodeAGENTS.md, local MCP
Antigravity.agents/agents.md, .agents/skills/
Gemini CLIGEMINI.md, local MCP configuration
AGENTS.md-compatible toolsAGENTS.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, .env values, 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

Discovery

npx skills add imMamdouhaboammar/agent-kernel -a claude-code -g -y
npm install -g @mamdouh-aboammar/agent-kernel

Discovery 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.json

License

MIT © Mamdouh Aboammar

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.