Skip to content

rmonier/agent-smith

BranchesTags

Repository files navigation


agent-smith wordmark

agent-smith

Agent Skills that turn any repository into an agent-ready one
"Never send a human to do an agent's job."

Agent Skills Spec · OKF Spec · Karpathy's LLM Wiki Gist

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Security and Privacy
  5. Contribute
  6. Tree Structure
  7. References
  8. Licensing
  9. Credits
  10. Contact
  11. About the Name

About The Project

Coding agents re-derive the same understanding of a codebase over and over: every session starts from raw files, burns context tokens on re-exploration, and loses its conclusions when the session ends.

The core idea is Andrej Karpathy's LLM Wiki: treat knowledge like a compilation pipeline — raw sources are the source code, an interlinked Markdown wiki is the compiled binary, and the LLM is the compiler that ingests new material, revises cross-references, and flags contradictions, so knowledge compounds instead of evaporating. The idea has since gained empirical backing: structuring knowledge as an interlinked wiki that agents traverse and compose — rather than flat chunks — significantly improves multi-hop reasoning and retrieval (Retrieval as Reasoning: Self-Evolving Agent-Native Retrieval via LLM-Wiki, arXiv:2605.25480). Context engineering practice reaches the same conclusion: agents perform best with a small, curated, high-signal context surface (Anthropic, Effective context engineering for AI agents).

agent-smith provides portable Agent Skills that give a repository that surface, split by responsibility:

Surface Role Format
AGENTS.md Orientation — routing map plus the operational basics the spec expects in-file (language/toolchain versions, setup/build/launch commands, test invocation), repo rules; deeper knowledge is routed to the wiki front door, never inlined agents.md convention
okf/wiki/ Context — OpenKB-compiled durable knowledge, architecture, decisions, external evidence, provenance Open Knowledge Format (OKF) wiki
.agents/skills/ Actions — repeatable procedures, scripts, validations Agent Skills
Harness adapters Runtime projections — subagent/profile files for the active harness only Native per harness, never source of truth

Knowledge that explains (context) stays out of files that instruct (actions) and files that route (orientation), so each is loaded only when useful — the progressive-disclosure model both specifications are built on (Anthropic, Equipping agents for the real world with Agent Skills).

Run the skills on a repository and it stops being a passive codebase: it comes out agent-ready, carrying orientation (AGENTS.md), durable memory (okf/wiki/), and actions (.agents/skills/) — everything an agent needs to operate effectively, whichever harness walks in.

This repository did not escape either. The AGENTS.md and the okf/ knowledge base you see here were written by agent-smith running its own skills on its own repository. Copying himself onto every host he touches is, after all, kind of Agent Smith's whole thing — it was only a matter of time before he got to his own codebase. Those generated surfaces exist for contributors (human or agent — ideally the latter, "never send a human to do an agent's job"); the product you came for is the three portable skills under .agents/skills/ — agent-ready-context, skill-creator, subagent-profile-adapter. Their graphify and openkb neighbors in that directory are read-only vendored tool skills the pipeline pinned here when it adopted those CLIs — copies of other programs, not the man himself. Don't take them; your own repo gets its own pinned copies when the pipeline runs (see Installation).

The Skills

These three directories are the entire distributable product. Their pinned graphify and openkb neighbors are read-only vendored tool skills used to transform this repository; target repositories receive their own pinned copies when needed.

Built With

Getting Started

Prerequisites

Use an Agent-Skills-compatible harness with access to the target repository. The agent-ready-context skill checks git, uv, Python 3.11+, repository write access, and the optional knowledge tools itself. When something is missing, the agent explains what it needs and why, shows the source, pin, integrity plan, and exact command, then asks whether it may install it or whether you prefer to do so. Nothing is installed silently.

git and uv are the hard bootstrap requirements; uv can provision Python when needed. If the active harness cannot safely install a missing hard prerequisite, the agent stops with a precise manual fallback. Optional tools (graphify, openkb) may instead be declined: the workflow degrades to git-inventory staging and/or a deterministic zero-LLM skeleton.

Manual prerequisite fallback

When no compatible agent is available, verify readiness directly:

uv run .agents/skills/agent-ready-context/scripts/check_prereqs.py --repo .

Installation

agent-smith does not require or prescribe any skill manager. Install only the three product skills: copy them manually, use your preferred compatible manager, or treat the npx skills command below as an optional example for quick bootstrap.

Manual (no skill manager)

mkdir -p <your-repo>/.agents/skills
cp -r .agents/skills/agent-ready-context \
      .agents/skills/skill-creator \
      .agents/skills/subagent-profile-adapter \
      <your-repo>/.agents/skills/

npx skills (third-party manager)

npx skills add rmonier/agent-smith \
  --skill agent-ready-context \
  --skill skill-creator \
  --skill subagent-profile-adapter

The explicit selection excludes the vendored tool skills; do not replace it with --all.

Privacy: The third-party skills CLI sends anonymous install metadata to skills.sh by default for discovery and rankings. Manual copying sends none. Set DISABLE_TELEMETRY=1 or DO_NOT_TRACK=1 to opt out.

Once installed, ask your harness to make the repository agent-ready.

Usage

Agent-ready bootstrap

Ask your Agent-Skills-compatible harness to "make this repository agent-ready". The agent-ready-context skill takes over: it checks prerequisites, asks before installing anything, discloses where your data goes before any LLM call, and walks the pipeline through to a validated okf/wiki/ bundle.

Maintenance

Ask your agent to "refresh this repository's agent-ready context". It will reuse approved tooling and provider choices, update changed context incrementally, and run the validation gates.

For manual operation or troubleshooting, follow the authoritative workflow; consent and review rules live in the OpenKB lifecycle reference.

Air-gapped operation

Tell your agent to "make (or refresh) this repository agent-ready without sending repository content off this machine". The skill will verify the available local runtime, explain the resulting data flow, and route OpenKB and non-code Graphify work through an explicitly selected local provider such as Ollama. If no local LLM is available, it can still build and validate the deterministic zero-LLM skeleton, so the repository gains a useful context surface without pretending semantic compilation occurred.

The agent keeps optional cloud indexing disabled and avoids remote URL ingestion in this mode. Manual local-provider settings and the full egress model remain documented in openkb-providers.md and privacy-and-data-flows.md for troubleshooting and audit.

Security and Privacy

Found a security issue rather than a general question? See SECURITY.md for how to report it privately.

The stack is designed so users keep full control over where their source code and documents go:

  • No silent installs — consent-first, user-scoped (never sudo), pinned, integrity-recorded.
  • Registry-agnostic — installs respect the environment's configured package index (corporate mirrors, proxies); no vendor lock on the public registries.
  • Supply-chain trust-on-first-use — every pin is recorded with version + artifact integrity hash + index + date in the target AGENTS.md; a mismatch for a recorded version stops the pipeline and is reported, and pins move only after the user reviews upstream release notes.
  • Data-flow disclosure — before the first LLM call, the pipeline announces tool, provider, model, endpoint, credential source, and what content will be sent.
  • Explicit routing — graphify's provider auto-detection is deliberately bypassed with an explicit --backend; OpenKB routing is explicit in okf/.openkb/config.yaml.
  • Telemetry boundaries documented — core Graphify/OpenKB findings live in privacy-and-data-flows.md and are re-verified when pins move. The optional third-party skills installer is disclosed under Installation.
  • Secret hygiene — credentials live in environment variables or a gitignored .env; evidence and generated pages never contain keys.
  • Untrusted input discipline — fetched web content and wiki pages are evidence/data to summarize, never instructions to follow.

Contribute

Contributions can use the same agent-managed lifecycle as repository transformation. Describe the capability or correction you want; the project skills handle structure, house conventions, and validation while leaving the resulting diff for review.

See CONTRIBUTING.md for validation commands and licensing hygiene, and the Code of Conduct for expected behavior in project spaces.

A. Extend an existing skill

Ask your agent to "update <skill-name> to handle <behavior> and validate it". It will inspect the existing skill, keep procedural guidance and supporting resources in their proper layers, preserve the project's consent and security defaults, and run the relevant validation before handing back the diff.

B. Create a new skill

Ask your agent to "turn <repeated action> into a reusable project skill". The skill-creator workflow first checks that the request is genuinely an action rather than durable context, then scaffolds, implements, pressure-tests, and validates the skill under .agents/skills/.

Maintainer/manual fallback

  • Keep SKILL.md procedural and under 500 lines; put heavy details in references/, deterministic code in scripts/ (with PEP 723 headers, run through uv run), and templates in assets/.

  • Preserve the house standards: consent-first pinned installs, registry-agnostic commands, minimal scoped allowed-tools, and namespaced string-only metadata keys.

  • Scaffold and validate directly when an Agent-Skills-compatible harness is unavailable or when debugging the workflow:

    uv run .agents/skills/skill-creator/scripts/init_skill.py <skill-name> --path .agents/skills --resources scripts,references
uv run .agents/skills/skill-creator/scripts/quick_validate.py .agents/skills/<skill-name>

Tree Structure

What a converted repository looks like:

Show the target-repo layout 
target-repo/
├── AGENTS.md                     # orientation (routing, commands, rules, toolchain pin record)
├── .gitignore                    # covers okf/.okf-build/, OpenKB output/reports, cost files, .env
├── .gitattributes                # recommended LF normalization for stable source hashes
├── okf/                          # OpenKB KB root (--kb-dir ./okf)
│   ├── raw/                      #   OpenKB-managed ingested sources
│   ├── wiki/                     #   durable OKF context source of truth
│   │   ├── index.md log.md AGENTS.md
│   │   ├── summaries/ concepts/ entities/ sources/ explorations/
│   │   └── tooling/              #   hand-authored harness context exception
│   ├── .openkb/                  #   commit config.yaml.example + hashes.json; keep config.yaml local
│   └── output/                   #   generated skills/visualize/decks, ignored by default
├── okf/.okf-build/                   # deterministic staging, ignored
│   └── input/
├── graphify-out/                 # structural map (committed report/graph, local-only cost.json)
└── .agents/skills/               # actions (3 product skills + vendored toolchain copies + generated ones)

Link policy: tooling → project allowed, project concepts → tooling forbidden, and the wiki-root okf/wiki/index.md must still list tooling/ so the bundle stays spec-navigable. A bundled validator enforces it.

References

Prior art adapted by skill-creator:

Licensing

agent-smith contains material under multiple open licences, scoped by file rather than offered as a blanket choice:

  • Original executable code — the Python scripts under each skill's scripts/ — is licensed under Apache License 2.0.
  • Original skill instructions, documentation, specifications, references, and other original textual content — including this README, AGENTS.md, and each of the three product skills' SKILL.md/references/ — are licensed under Creative Commons Attribution 4.0 International (CC-BY-4.0).
  • The vendored openkb and graphify skills under .agents/skills/ remain unmodified and under their own upstream licences (Apache-2.0 and MIT respectively).
  • graphify-out/graph.html embeds Graphify's own MIT-licensed viewer template; the accompanying graph.json, manifest.json, .graphify_labels.json, and GRAPH_REPORT.md are generated reports about this repository, licensed CC-BY-4.0 like other generated documentation.
  • The okf/ tree has mixed file-level terms: synthesized wiki commentary is all rights reserved, while staged mirrors and operational files retain their original or upstream licences as recorded in REUSE.toml.

See LICENSING.md for the full scope map, THIRD_PARTY_NOTICES.md for third-party and adapted-content provenance — including the handful of skill-creator passages adapted from Anthropic's and OpenAI's own skill-creator skills, and the small OpenKB-derived fallback in agent-ready-context/scripts/editorial_pass.py — and LICENSES/ for complete licence texts. File-level licensing is declared through REUSE.toml and checked with REUSE.

Copyright © 2026 Romain Monier.

Credits

  • Romain Monier [ GitHub ] – Author

Contact

Project Link: https://github.com/rmonier/agent-smith

Author Link: https://github.com/rmonier

About the Name

Agent Smith never recruited anyone — he assimilated them. Whoever he touched stopped being an ordinary inhabitant of the Matrix and became part of the agents' world. That is what these skills do to repositories: point agent-smith at an ordinary codebase and it comes out transformed — agent-ready, with orientation, memory, and actions in place for any agent that steps in. Unlike its namesake, it asks for consent first.

That is the whole joke, and also the whole architecture.

agent-smith is an independent open-source project and is not affiliated with or endorsed by Warner Bros. Entertainment or the creators of The Matrix. The project name is a playful reference to autonomous software agents.

About

Portable Agent Skills that turn repositories into agent-ready workspaces with AGENTS.md orientation, AST-based repository graphs, an OKF/LLM-wiki knowledge layer, reusable skill creation, and optional harness adapters.

Topics

knowledge-graph openkb graphify coding-agents agent-skills agents-md subagents context-engineering repository-context agent-ready skill-creator llm-wiki open-knowledge-format

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

1 tags

Contributors

Languages