Skip to content
Agent Fundamentals

Overview

Everything the workflow needs lives in one folder at the root of the repository:

.agent/
├── AGENT.md          # the workflow contract — how the agent works here
├── plans/            # what we intend to build (markdown, one file per plan)
├── board/            # the kanban board (one markdown file per ticket)
│   └── history/      # append-only log per ticket (JSONL)
├── skills/           # reusable instructions for the agent
│   └── <name>/SKILL.md
└── tools/            # small checked programs the skills call
    └── <name>/TOOL.md + one implementation per platform

Three properties make this work:

  • Plain files. Plans, tickets, skills, and tool contracts are markdown with YAML frontmatter; history is JSONL. Everything is reviewable in a diff and survives any tool change.
  • Agent-agnostic. AGENT.md is the single source of truth for the workflow. Agent-specific entry points (CLAUDE.md, AGENTS.md) only point to it, and agent-specific skill folders such as .claude/skills are symlinks into .agent/skills/ — add a skill once, every agent sees it.
  • Two readers, one state. The agent reads and writes these files from the terminal; the iKanban AI app renders the same files for the owner. There is no synchronization problem because there is nothing to synchronize.

The rest of this section covers the building blocks in turn: skills (what the agent knows how to do), tools and tool specs (small programs with a strict, testable contract), and MCPs (how an agent reaches beyond the file system).