Teach your agent

Every coding agent already reads instruction files from your repository. Tellscript needs only a few lines in the file your agent reads, and the agent keeps the Tellscript up to date as it works.

Install the skill

The Tellscript skill teaches your agent the whole format and when to use it. One command installs it for Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode and other agents that read Agent Skills:

npx skills add tellscript-dev/tellscript

In Claude Code you can add it as a plugin instead:

/plugin marketplace add tellscript-dev/tellscript
/plugin install tellscript@tellscript

The skill, the spec and the schema live in the tellscript-dev/tellscript repository.

One prompt, any agent

No installer at hand? Paste this into the agent you use. It teaches the agent the format from this site and writes the instructions into your repository, so the next session knows them too.

Learn the Tellscript format from
https://tellscript.com/llms-full.txt

Then add a short "Tellscript" section to the instruction
file you read here (AGENTS.md, CLAUDE.md, GEMINI.md,
.cursor/rules or .github/copilot-instructions.md):

- tell/ is the source of truth for what this app must
  do and look like. Read the matching file before
  changing behaviour.
- Never break a fixed statement. Propose changes to
  guided sections; improve free sections freely.
- New or changed behaviour updates tell/ in the same
  change: a stable id and a check per statement.

The lines to add

If you prefer to write it yourself, this is the section. It is the same for every agent; only the file differs.

## Tellscript

tell/ is the source of truth for what this app must do, how it looks
and why. Format: https://tellscript.com/docs

- Before changing behaviour, read the matching file in tell/.
- Fixed sections are rebuilt exactly. Never change a fixed statement
  to make a test pass; propose a decision instead.
- Guided sections: propose improvements with a measurable gain.
- Free sections: improve them freely; only the checks decide.
- New or changed behaviour updates tell/ in the same change:
  a stable id, one checkable sentence, and a → line to its check.

Where each agent reads it

For agents: the format as plain text

Agents do not need the website. Every docs page is also available as Markdown, and the whole format fits in one file:

• llms.txt: an index of all docs pages, for agents that browse.
• llms-full.txt: every docs page in one file, to paste into a context window.
• Any docs page with .md appended, for example /docs/statements.md.