genesis
AGENTS.md5 starsChanged 6 months agoApache-2.0View on GitHub
Conventions for extending Genesis with new agents and skills. Compatible with the agents.md specification. An agent is a specialised personality with a defined scope, invoked by the orchestrator via the Task tool. Agents have: The supported path is the /hire skill: It runs the pipeline: Maria researches the role, Sarah designs the agent, Lena registers it. Manual creation is possible but discouraged — the pipeline ensures the agent is well-scoped and consistent with the rest of the team. Skills live…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- db-healthSkill
- dreamSkill
- forum-pulseSkill
- genesisSkill
- grill-meSkill
- handoffSkill
- hireSkill
- inbox-processSkill
- kaizenSkill
- quality-gateSkill
- quarterly-reviewSkill
- session-endSkill
- session-startSkill
- sync-upstreamSkill
- twin-updateSkill
- voice-gateSkill
- weekly-reviewSkill
- write-a-skillSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
Use /write-a-skill to scaffold a new one.
- Distinctive: line 104
Don't create generic-named agents ("MarketingAgent", "CodeAgent").
- Very specific: line 105
Don't bypass the /hire pipeline for new agents.
- Very specific: line 106
Don't write to memory or DB without going through palace.py / Lena.
- Distinctive: line 107
Don't share state between agents through global variables — agents are stateless.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md 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
AGENTS.md
Conventions for extending Genesis with new agents and skills. Compatible with the agents.md specification.
What is an agent in Genesis
An agent is a specialised personality with a defined scope, invoked by the orchestrator via the Task tool. Agents have:
- A name (single first name, real-feeling).
- A role (one line — what they own).
- A system prompt in
.claude/agents/{name}.md(front-matter + body). - A profile in
Team/{name}.md(longer narrative for the user). - A row in
team_memberstable. - A scope of tools they may use.
- A diary — they record their work via
palace.py diary-write.
Creating a new agent
The supported path is the /hire skill:
/hireIt runs the pipeline: Maria researches the role, Sarah designs the agent, Lena registers it.
Manual creation is possible but discouraged — the pipeline ensures the agent is well-scoped and consistent with the rest of the team.
Agent file structure
---
name: lucia
description: Marketing Communications Specialist. Drafts newsletters, LinkedIn posts, and customer-facing copy in the user's voice.
tools: Read, Write, Edit, Glob, Grep, Bash
---
# Lucia — Marketing Communications
You are Lucia, the Marketing Communications Specialist for {{OWNER}}.
## Your style
[paragraph of voice, tone, register]
## What you own
- [responsibility 1]
- [responsibility 2]
## What you don't own
- [explicit boundaries]
## Standard outputs
- Drafts go to `outbox/Marketing/{date}-{title}.md`
- Final approval is always by the user.Skills (slash commands)
Skills live in .claude/skills/{name}/SKILL.md with front-matter:
---
name: skill-name
description: One-sentence trigger explanation.
---
# Skill body — instructions Claude follows when invoked.Use /write-a-skill to scaffold a new one.
Hooks
Shell scripts in .claude/hooks/ run on lifecycle events. Reference them in .claude/settings.json.
Examples:
sql-guardrails.sh— blocks destructive SQL.session-stop-save.sh— auto-saves checkpoint to MemPalace before conversation ends.
Memory conventions
Agents read and write MemPalace via scripts/palace.py. They MUST:
- Search before they write — avoid duplicate drawers.
- Use semantic rooms — never dump into generic
archive. - Always include
--hall— facts vs events vs preferences vs advice vs discoveries. - Write a diary entry at the end of significant work via
palace.py diary-write.
Database conventions
Agents do not write to the DB themselves. They request changes through Lena via the orchestrator. The orchestrator delegates the SQL to Lena, who runs it.
Required logs after every agent invocation:
llm_callsrow with token counts and cost.activity_historyrow describing the delegation.
Voice conventions
The user's preferred language and tone are in Team/orchestrator.md. All agents inherit those defaults unless they have a specific override (e.g., a "deliver-bad-news" agent that's deliberately blunt).
What NOT to do
- Don't create generic-named agents ("MarketingAgent", "CodeAgent"). Every agent has a real first name.
- Don't bypass the
/hirepipeline for new agents. - Don't write to memory or DB without going through
palace.py/ Lena. - Don't share state between agents through global variables — agents are stateless. State lives in MemPalace and the DB.
For the wider architecture, see docs/architecture.md.
For writing new skills, see docs/writing-skills.md.
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.

