BorjaIPBorjaIP/personal-os-skills/AGENTS.md

personal-os-skills

AGENTS.md1 starsChanged 33 days agoMITView on GitHub

Personal collection of agent skills plus the scripts that install them and the surrounding harness. Read this before changing or running anything here. .atl/ is generated by Gentle AI (skill registry). Never commit it. Never install, update or configure anything without an explicit selection from the user. Without a terminal, setup.sh, install.sh and install-external.sh exit with code 2 if no selection is given. bootstrap-harness.sh without --only acts on its default set (T3, Pi, Gentle AI, Engram and the CLIs in…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository13 other files it gives its agents.
- capture-insightsSkill
- create-runbookSkill
- datadog-logs-analyzerSkill
- datadog-metrics-investigatorSkill
- datadog-report-publisherSkill
- datadog-service-healthSkill
- datadog-triageSkill
- k8s-error-analyzerSkill
- k8s-optimizer-costSkill
- meeting-notes-enhanceSkill
- runSkill
- second-opinionSkill
- stack-updaterSkill

The file

We split this AGENTS.md into the rules it gives an agent

8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Never install, update or configure anything without an explicit selection from the user.
line 22
Very specific:
Run ./setup.sh --list (or --list tools|external|families).
line 24
Distinctive:
Ask which items the user wants.
line 25
Very specific:
Run ./setup.sh --only <ids> --yes (add --dry-run to preview).
line 26
Very specific:
Verify a repository's skill names read-only with npx --yes skills@<version> add <owner/repo> --list.
line 51
Very specific:
Write SKILL.md in English.
line 56
Very specific:
Follow the skill-creator style guide: frontmatter (name, one-line quoted description of at most 250 characters starting with Trigger:, …
line 57
Very specific:
No test runner exists. Verify with bash -n <script>, --dry-run, and --list.
line 65

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Personal collection of agent skills plus the scripts that install them and the surrounding harness. Read this before changing or running anything here.

Layout

Path	Purpose
`skills/<name>/SKILL.md`	The repo's own skills (plus optional `assets/`, `references/`)
`external/catalog.tsv`	Third-party skill repositories that can be installed on demand
`setup.sh`	Single entry point: menu and `--only` over the three scripts below
`install.sh`	Installs this repo's skills by family into Claude Code, Cursor and Pi
`install-external.sh`	Installs catalog entries into every harness detected on the machine
`bootstrap-harness.sh`	Installs and configures T3 Code, Claude Code, Codex, Cursor CLI, Pi, Gentle AI, Engram
`odd/tasks/<feature>.md`	Tracking document for substantial work
`docs/`	Per-area documentation

.atl/ is generated by Gentle AI (skill registry). Never commit it.

Installing: always ask first

Never install, update or configure anything without an explicit selection from the user.

Run ./setup.sh --list (or --list tools|external|families).
Ask which items the user wants.
Run ./setup.sh --only <ids> --yes (add --dry-run to preview).

Without a terminal, setup.sh, install.sh and install-external.sh exit with code 2 if no selection is given. bootstrap-harness.sh without --only acts on its default set (T3, Pi, Gentle AI, Engram and the CLIs in --agents) after asking for confirmation, so pass --only when calling it directly.

Group	Examples	Handled by
Tools	`t3`, `claude-code`, `codex`, `cursor`, `gentle-ai`, `engram`, `pi`	`bootstrap-harness.sh`
External skills	`diagram-design`	`install-external.sh`
Skill families	`kubernetes`, `datadog`, `ops`, `productivity`, `harness`	`install.sh`

Families are mapped by skill name in skill_family() in install.sh; a new skill that matches no pattern falls into other.

Harness detection

Scripts install only where a harness exists and report the rest.

install.sh: Claude Code (claude or ~/.claude), Cursor (cursor-agent or ~/.cursor), Pi (pi or ~/.pi, skills in ~/.agents/skills).
install-external.sh: Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, Codex, Pi, Windsurf. The table lives in harness_table(); add a harness there only after checking its global skills directory in the skills CLI README.
bootstrap-harness.sh configure targets only agents whose CLI is installed.

External skills

A catalog line is id, owner/repo, skills (comma-separated or *), license, description, separated by tabs.
They are third-party: they add instructions, and sometimes scripts, that agents follow. Review a repository before listing it, show source and license before installing, and require confirmation.
Installation goes through npx skills@<pinned version> (SKILLS_CLI_VERSION in install-external.sh). Bump the pin deliberately, not automatically.
Verify a repository's skill names read-only with npx --yes skills@<version> add <owner/repo> --list.
The skills CLI has no check-only update mode, so latest versions are reported as unknown.

Writing skills

Write SKILL.md in English.
Follow the skill-creator style guide: frontmatter (name, one-line quoted description of at most 250 characters starting with Trigger:, license, metadata.author, metadata.version), then Activation Contract, Hard Rules, Decision Gates, Execution Steps, Output Contract, References. Keep the body under 1000 tokens and move detail to assets/ or references/.
install.sh treats any file containing {{UPPER_CASE}} as a placeholder template and installs a rendered copy instead of a symlink. Do not write that pattern literally in scripts or docs inside a skill.
Register a new skill in README.md and .claude-plugin/marketplace.json.

Shell conventions

bootstrap-harness.sh sets IFS to newline and tab. Split lists with IFS=',' read -r -a, not by unquoted expansion.
install.sh and setup.sh run with set -euo pipefail. A function whose last command may legitimately fail must end with return 0.
No test runner exists. Verify with bash -n <script>, --dry-run, and --list. Do not run real installs to test.

Workflow

Branch off main; do not commit to main.
Conventional commits, one per work unit, with docs alongside behavior. No AI attribution lines.
For work with two or more steps, create odd/tasks/<feature>.md before the first change and keep it updated.
The user decides pushes, pull requests and merges.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free