Blocks, explained

An interactive guide to every block in Skill Builder: what each one is for and when another fits better, the markdown it writes for SKILL.md, agent files and AGENTS.md, and the checks it gets. Try the fields live; nothing is saved. The interactive version needs JavaScript.

Structure

  • Callout
    One note, tip or warning that must stand out from the text around it.
  • Divider
    A visual break between two unrelated parts of a long file.
  • Heading
    A section heading on its own, for example above a few reference blocks.
  • Project overview
    The first block of AGENTS.md: what the project is and who it is for.
  • Project structure
    Where things live, so the AI finds the right files first.
  • Role
    The agent's identity, expertise and mission.
  • Tech stack
    Languages, frameworks and main libraries, with the versions that matter.
  • Title & overview
    The first block of a skill or agent: its name as a heading and what it is for.

Instructions

  • Arguments
    What the text after /name means, for skills people start themselves.
  • Commands
    The exact commands to install, run, build, test and lint, so the AI can check its work.
  • Gather context first
    Files to read and commands to run before the work starts.
  • Git and pull requests
    Branches, commit messages and what a pull request needs.
  • Output format
    Exactly what to produce or hand back, and in what shape.
  • Principles
    A few guiding ideas, each with a short reason, where judgment matters more than steps.
  • Responsibilities
    What the agent owns, so it does not drift into other work.
  • Step-by-step process
    An ordered procedure to follow. Not for conditions, links or rules.
  • Testing
    How tests are written and run, and what must pass before a change is done.
  • When to use
    When this skill or agent should be used (triggers) and when not to.

Examples

  • Code snippet
    A piece of code to copy or follow exactly, with its language.
  • Example
    Show one input and the output you expect. Examples teach format faster than rules.

Constraints

  • Anti-patterns
    Mistakes the AI tends to make here, so it avoids them.
  • Architecture rules
    Decisions the AI must respect, such as layers and where logic goes.
  • Boundaries
    What the agent always does, asks about first, and never does.
  • Boundaries
    What every AI tool always does, asks about first, and never does in this project.
  • Checklist
    Things to check before finishing.
  • Code style
    Naming, formatting and patterns a linter does not already enforce.
  • Completion goal
    Work that repeats (fix, check, fix again): the goal, the check, the limit and what happens next.
  • Definition of done
    What has to be true before the whole task is finished, and how to check it.
  • Path rules
    Point Codex and other AI tools at each path rule and its files. Lists the project's rules.
  • Rules
    Constraints and conventions that always apply.
  • Security
    Secrets, personal data and anything that must never leave the project.

Tools

  • Agent reference
    Hand work off to another agent of the project, and say when.
  • Bundled resources
    List the scripts and files shipped with the skill, and whether to run or read each.
  • References
    Links to outside documentation or files the AI can load when it needs them.
  • Repository skills and agents
    Skills and agents installed in the repository itself, and when to use each.
  • Resource link
    Tell the skill when to read one of its own files (references/, scripts/, …).
  • Skill Builder (Connect AI)
    Tell AI tools to load skills and agents from Skill Builder when they are not installed.
  • Skill reference
    Make this agent or skill use another skill of the project, and say when. It also links the skill.
  • Skills and agents
    List this project's skills and agents with when to use each. It stays up to date.
  • Tool guidance
    How and when the agent uses each tool.

Custom