Working with AI

!Note: this page is auto-generated from docs/working-with-ai.md.

Head Start ships with first-class support for AI coding agents. This covers the three pieces that make it work: agent instructions (AGENTS.md), domain skills (.agents/skills/), and MCP servers (.mcp.json).

Agent instructions

AGENTS.md at the repo root is the primary entry point for any AI coding agent. It contains the project overview and philosophy, required reading, environment setup, build/run/test commands, code style, GraphQL/CMS workflow, security considerations, guardrails, and known rough edges.

Most MCP-compatible agents (Claude Code, Cursor, GitHub Copilot, etc.) pick this file up automatically when you open the repository.

Agent skills

Skills are reusable capability bundles that give agents focused, project-validated guidance for a specific domain. They are part of the open agent skills ecosystem and are managed via the skills CLI.

Project skills are vendored into .agents/skills/, one directory per skill. Each contains a SKILL.md whose frontmatter description declares its trigger — agents discover and load them on demand. Sources are pinned in skills-lock.json. It is auto-managed by the skills CLI — don't edit it by hand.

Adding or updating a skill

Browse available skills at skills.sh, then:

npx skills add <owner/repo>

This vendors the skill into .agents/skills/ and updates skills-lock.json. No further documentation is needed — the SKILL.md is the source of truth for when to load it.

To refresh installed skills, re-run npx skills add against their source. Review the diff in .agents/skills/ before committing — treat upstream skill updates the same as a dependency bump.

To remove a skill, run npx skills remove <name> and verify skills-lock.json is updated.

MCP servers

Model Context Protocol (MCP) servers give agents live access to external tools and data sources beyond their training knowledge. The project's MCP servers are configured in .mcp.json, which is picked up automatically by Claude Code, Cursor, and other compatible agents. Read the file for the current list.

stdio-based servers are launched on demand via npx — no global install needed. HTTP-based servers connect to remote endpoints directly.

Security: the hosted datocms server authenticates via OAuth in your browser — no token in config. If you add a stdio server that needs a secret, read it from your shell environment via ${VAR} interpolation. Never hardcode tokens in .mcp.json — it is committed to the repository.