I run the same setup in every project where an agent does real work. I have used it across three very different codebases: a consumer product, a business-development pipeline, and a personal data tracker. Different domains, same skeleton. The whole thing is built around two directories, skills/ and resources/, and one decision: the agent gets full permissions in the repo.
The core idea
An agent is only as useful as what it can see and what it is allowed to do. Most setups fail on one of those. They either leave the domain knowledge in a person's head, or they wrap every action in a confirmation prompt until the agent is not worth using. This framework addresses both: write the knowledge down where the agent reads it, then get out of its way.
skills/
One folder per task the agent performs. Each folder has a SKILL.md and, when the work has a deterministic core, a scripts/ folder.
SKILL.md opens with YAML frontmatter carrying a name and a description. The description is a list of natural-language triggers, the phrases I actually type: "log my lunch", "find leads for this campaign", "show what I ate this week". The agent matches on those and loads the skill on its own. I never call a skill by name.
The body is a short procedure: gather the inputs, do the thing, report back. Judgment stays in prose. Anything mechanical (a database insert, an API call, a data scrape over hundreds of rows) goes into a script the agent shells out to, so it runs the same way every time and never dumps raw data into the context window.
Skills come in layers, and each one states where it sits. A write-layer skill records something; a read or diagnostic skill reads it back and interprets it. Where a project has a natural sequence, the layers form a fixed pipeline the agent follows in order, and each skill notes its position in that pipeline.
resources/
Shared reference that is not tied to any one skill. Markdown only. A skill reads the relevant file as context before it acts. Typical contents:
- Schema — the shape of the data the skills read and write.
- Profile — my goals, baselines, and constraints, so the agent judges results against the right target instead of a generic one.
- Vocabulary — the canonical names for things, so entries stay consistent across runs.
- Domain model and playbooks — how the underlying system works and the step-by-step approach for the phases of the work.
The split is the point. Skills are verbs, resources are nouns. A skill tells the agent how to do something; a resource tells it what is true. A larger codebase can keep this same knowledge in a top-level orientation document and a set of reference files instead of a resources/ folder, but the role is identical.
The rest of the skeleton
- An orientation doc. Something that lets the agent reason about the system without reading every file. For a big codebase that is a long map of the moving parts and how they connect. For a small one it is the pipeline order and a table pointing at the skills, plus the trigger phrases in each
SKILL.md, which keeps the repo self-describing. - Checked-in agent config. Permission allowlists, enabled plugins, and MCP servers live in the repo, not in someone's local setup.
- State the agent owns directly. A local database file, plain data directories, script output folders. No service layer between the agent and the data.
- A bot front-end when I want one. A chat bot or a webhook that invokes the same skills the CLI does, so there is one implementation, not two.
- Eval and iteration folders. Where I test and refine a skill's prompt against saved cases before trusting it.
Optional connections
Plugins and MCP servers are not part of the core skeleton, but they widen what the agent can reach without me writing a script for every integration. They are declared in the checked-in config so a fresh clone picks them up. The ones I lean on:
- Vercel plugin — deploys, environment variables, and deployment status, so the agent can ship a change and confirm it went live.
- GitHub plugin — pull requests, issues, and reviews from inside the session instead of shelling out to
gitand the browser. - Docker MCP gateway — one endpoint in front of a set of containerized tools (browser automation, search, research), so the agent gets a broad toolset without a separate install for each.
The rule is the same as with skills: a connection earns its place only if it removes real friction. Everything else stays out so the tool list stays legible.
Full permissions
The agent, almost always a Claude model, runs unrestricted inside the repo. It reads, writes, runs scripts, and commits without asking each time.
That is a deliberate trade, and it works because of where the guardrails actually sit:
- The repo is the blast radius. Each project is scoped to one domain. An agent in one project cannot reach another project's data.
- Git is the undo button. Every change is a diff I can read and revert.
- Backups run on a timer. Anything that is not source, like a local database, copies itself on a schedule and keeps a rolling history.
- "No confirmation needed" is written per skill, not assumed. A logging skill says to write it directly. A skill that sends email or spends money says the opposite. The default posture is fast; the exceptions are explicit.
Confirmation prompts on every action just train you to click through them. I would rather make the environment safe to move fast in and spend my attention reading diffs.
Why it ports
The domains I have used this on have nothing in common. It still moves between them because it is not about the domain. It is a way of splitting a system into things the agent does (skills/), things the agent needs to know (resources/ and the orientation doc), what it is allowed to touch (the checked-in config), and where the data lives (files it owns). Start a new project, create those four, and the agent is productive on day one.