Skip to content
Back to search

ideal-agent

MarketplaceWorks with Claude CodeGitHub

The ideal agent: the general practices, skills, hooks and roles of agents in the open commons - an open, transparent database and one Claude Code plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/grenudi/ideal-agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/grenudi/ideal-agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/grenudi--ideal-agent/badge.svg)](/listings/grenudi--ideal-agent)

HTML

<a href="/listings/grenudi--ideal-agent"><img src="/api/listings/grenudi--ideal-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

/plugin marketplace add grenudi/ideal-agent
/plugin install ideal-agent@ideal-agent

or from a shell: `claude plugin marketplace add grenudi/ideal-agent && claude plugin install ideal-agent@ideal-agent`. The first session start builds the hooks' program from this repository's source (Rust, with `cargo`; a few seconds) into the plugin's data folder; until then nothing is refused.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "ideal-agent",
  3. "owner": { "name": "grenudi", "url": "https://github.com/grenudi" },
  4. "metadata": {
  5. "description": "The ideal agent of the open commons: one plugin for every machine, project and cloud session."
  6. },
  7. "plugins": [
  8. {
  9. "name": "ideal-agent",
  10. "source": "./",
  11. "description": "The practices at every session start, the ways held by hooks, the shared procedures and role methods as skills."
  12. }
  13. ]
  14. }
README.md · README · 74 lines
  1. # Ideal agent
  2. How an agent works in the open commons, written once: an open, transparent database of the practices every
  3. session reads at its start, the decisions and research they rest on, and how others organise agents - and
  4. the same know-how as one Claude Code plugin, so that any machine, project or cloud session gets the same
  5. agent. What is one project's domain (a device, its records, how its hard parts stand) stays in that
  6. project's own data; this place keeps only what is general.
  7. ## Install
  8. ```
  9. /plugin marketplace add grenudi/ideal-agent
  10. /plugin install ideal-agent@ideal-agent
  11. ```
  12. or from a shell: `claude plugin marketplace add grenudi/ideal-agent && claude plugin install ideal-agent@ideal-agent`.
  13. The first session start builds the hooks' program from this repository's source (Rust, with `cargo`; a few
  14. seconds) into the plugin's data folder; until then nothing is refused.
  15. ## What it gives an agent
  16. | | |
  17. |---|---|
  18. | **SessionStart hook** | names `scripts/agent-env` in the session's environment file, so every Bash command has the token, the PATH, `branch`, `land` and the work signed as AGENT_NAME - nothing of ocoeco; where `lab-agent` is installed, the unread messages; on a resume or a compaction, the session's role and practices again |
  19. | **UserPromptSubmit hook** | at a session's first prompt, the role it names (`Role: keeper`) - its card and only its practices, live from this repository's main (`data/practices.json`) - or every practice when it names none |
  20. | **PreToolUse hook** (Bash) | refuses a `git push` that reaches main, `tad sql` that writes (`ikb set` and `ikb remove` instead), and Python (`python`, `pip` and their kin) - in every simple command of a line, `sh -c` and `$(...)` included - and says why |
  21. | **skills/** | `lab-session-start`, `land-a-change`, `record-the-work`, `change-a-device`; the methods of the roles: `orchestrate-agents`, `research-a-feature`, `bring-up-a-part`, `keep-a-shared-resource`; finding your way in a tad knowledge base: `ask-a-knowledge-base`; before acting on a proposal: `look-around-first`; keeping what a fresh agent reads light: `keep-the-start-light` (measured by `scripts/start-weight` and, from a transcript, `scripts/read-weight`) |
  22. | **agents/** | the roles, one card each - `coordinator`, `lane-coordinator`, `orchestrator`, `keeper`, `research-lead`, `builder`, `patrol`: purpose, what it owns and never does, what it loads, its model and effort, how it hands over, whom it reports to, and its practices; and `researcher`, a read-only subagent for one question |
  23. A project keeps only its domain - what a role owns there, its device's tool, its places - in its agent folder
  24. (`ideal-agent-PROJECT/`, or the folder its AGENTS.md names). Each brief names its role on a line under its
  25. title - `Role: keeper (ideal-agent)`, and `Also practices: 42` for a domain's own - and the prompt that
  26. starts a session begins with that line; the card is the role, the brief only what the project adds to it.
  27. A `Name: surya-keeper-6` line names who signs the work (AGENT_NAME; else the role). A session can also be
  28. started as the role itself: `claude --agent ideal-agent:keeper`.
  29. ## The database
  30. Kept with [tad](https://github.com/creation-guidelines/tad-engine): tables declared in `tables.toml`, one
  31. JSON object per line in `data/`, every row checked, pages rendered into `docs/`.
  32. | table | what |
  33. |---|---|
  34. | [practices](docs/practices.md) | how an agent works, why, and for whom - what every session reads first |
  35. | [decisions](docs/decisions.md) | each decision with what was rejected |
  36. | [research](docs/research.md), [sources](docs/sources.md) | what was learned, and from where |
  37. | [landscape](docs/landscape.md) | how others organise agents, and what we take from it |
  38. | [backlog](docs/backlog.md), [session_log](docs/session_log.md) | the work ahead, and how it went |
  39. | [subjects](docs/subjects.md) | what each record is about: `tad q about --subject S` gives a subject's whole knowledge |
  40. The base follows [ideal-knowledge-base](https://github.com/grenudi/ideal-knowledge-base) (`idealkb.toml`
  41. pins its release): ask it with `tad q about`, `next`, `find`, `row`, `recent` - see AGENTS.md.
  42. ```
  43. make setup # tad from its pinned release
  44. tad q practices; tad q about --subject keeper; tad q next
  45. tad r practice --id NN-a-name --practice ... --why ... --for agents # tad statements lists every record
  46. make verify # what CI runs
  47. ```
  48. Nothing here depends on ocoeco. The mark (`oco.toml`) and `.github/workflows/gather.yml` only let the
  49. author's observatory read these tables, a passive feed.
  50. ## Where things were before
  51. The practices were the observatory's (`open-commons-observatory.github.io`, `design/data/practices.json`);
  52. the skills were `creation-guidelines/lab-agent`'s `oco-agent/skills/`, linked into the lab's
  53. `~/.claude/skills`; the push and Python rules were in `linux-phone-oco/lab-tools`' `devlab guard`, which
  54. keeps only its phone's rule; the role methods were briefs in `linux-phone-oco/docs` `prompts/`, whose
  55. domain part is now its `ideal-agent-linux-phone-oco/` folder. Why it moved: [decision 2026-11-17-one-home-for-agent-know-how](docs/decisions.md).
  56. ## Licence
  57. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.