Authoring a profile
A profile is a git repository that carries the AGENTS.md template plus RULES.md, rules/, tools/ and skills/. You don't build one from scratch — you start from the official profile template repository, fill it in, cut a release tag, and register it with install --profile.
This page covers producing that repository. To understand how a profile behaves once registered, read the Profiles model.
Start from the template
The starter lives in a GitLab template repository that already has the required layout and a working AGENTS.md template. Clone it, point it at your own repository, and start editing:
git clone https://gitlab.com/chagbrasil/agents-profile-template.git meu-profile
cd meu-profile
git remote set-url origin git@gitlab.com:workspace/meu-profile.git
Prefer to keep the template's history separate? Use GitLab's “Fork” or “Use this template” on the project page instead of
set-url.
The profile must stay complete — AGENTS.md, RULES.md, rules/, tools/ and skills/ all present — or install --profile refuses the clone and lists what's missing.
Anatomy of a profile
meu-profile/
├── AGENTS.md # the template rendered into each project (uses placeholders)
├── RULES.md # top-level agent rules
├── rules/ # granular rule modules (coding, security, workflow, …)
├── tools/ # tool docs (cli, mcp, …)
└── skills/ # Skills, one directory each with a SKILL.md; skills/README.md is the index
| Path | Purpose |
|---|---|
AGENTS.md | The one file that is rendered into every bound project. Everything else is referenced from here. |
RULES.md | Entry point for the agent's rules; the template links to the modules under rules/. |
rules/ | Granular rule modules (for example coding.md, security.md, workflow.md). |
tools/ | Documentation for the tooling the agent may use (for example cli.md, mcp.md). |
skills/ | One directory per Skill, each with a SKILL.md entry point; skills/README.md catalogs them. |
The AGENTS.md template
AGENTS.md is the only file agents-cli rewrites: at install --project time it is rendered into the project with the placeholders resolved, so agents never have to expand variables at runtime. Author it with the tokens below — they are substituted literally, and unknown tokens are preserved intact:
| Placeholder | Expands to |
|---|---|
{{AGENTS_PROFILE_HOME}} | Absolute path of the installed profile (no trailing slash). |
{{AGENTS_PROFILE_NAME}} | Name of the profile that generated the AGENTS.md. |
{{AGENTS_PROJECT_NAME}} | Registry label of the project (defaults to the folder name). |
Use {{AGENTS_PROFILE_HOME}} for every path that points back into the profile (rules, tools, skills), so the rendered file carries absolute, per-machine paths:
# {{AGENTS_PROJECT_NAME}}
Profile **{{AGENTS_PROFILE_NAME}}** — see the rules in
`{{AGENTS_PROFILE_HOME}}/RULES.md` and the skills index in
`{{AGENTS_PROFILE_HOME}}/skills/README.md`.
Keep the rest of the profile (RULES.md, rules/, tools/, skills/) as plain files — they are read in place from {{AGENTS_PROFILE_HOME}} and are never rewritten by the CLI.
Cut the first release
install / update --profile operate only on vX.Y.Z release tags (SemVer). A profile repository without any such tag fails with a message asking you to cut a release. Tag and push:
git add . && git commit -m "profile: initial content"
git push -u origin main
git tag v0.1.0
git push origin v0.1.0
install --profile pins the highest release tag (override with --version vX.Y.Z). Every subsequent change to the profile is shipped by cutting a new tag and running update --profile.
Register and test
Register the profile from its remote, then bind a throwaway project to verify the render:
agents-cli install --profile git@gitlab.com:workspace/meu-profile.git --name meu-profile
agents-cli list --profile
cd ~/Dev/algum-projeto
agents-cli install --project meu-profile # renders AGENTS.md with placeholders resolved
agents-cli doctor --project # validate the installation
Open the generated AGENTS.md and confirm every {{AGENTS_PROFILE_HOME}} resolved to the absolute profile directory and no placeholder was left behind.
Next steps
- Read the Profiles model: versioning by tags, binding, drift detection and guarantees.
- Follow the Quickstart end to end once your profile is published.
- Browse the Commands & flags reference for every subcommand and flag.