pinchos
customize-pinchosstandalone Agent Skill

Change your config with a second set of eyes.

The customize-pinchos skill helps an AI agent add and review canonical Pinchos items and ordered menu rows. It pairs the current schema with a cautious workflow for commands that can run with your user permissions.

1 · Install the skill

managed install

In Codex, invoke $skill-installer and give it the skill directory in the Pinchos repository.

Open the customize-pinchos directory on GitHub.

after install

Run /skills on your next turn and select $customize-pinchos. Restart Codex if it does not appear.

manual install

From a checked-out Pinchos repository, copy the complete directory into the standard user skill path.

$ (if [ -e "$HOME/.agents/skills/customize-pinchos" ]; then printf 'Refusing to overwrite %s\n' "$HOME/.agents/skills/customize-pinchos" >&2; exit 1; fi; mkdir -p "$HOME/.agents/skills"; cp -R skills/customize-pinchos "$HOME/.agents/skills/customize-pinchos")

The full README block checks the destination first and refuses to overwrite an existing skill.

The managed installer may use a configured Codex skills root. The manual path is $HOME/.agents/skills. These paths are separate.

2 · Invoke it for a change

Use $customize-pinchos when you want the workflow explicitly.

example request
$ $customize-pinchos
Add a read-only item that shows the current battery percentage.
Preserve the existing declaration order and validate the change before running it.

3 · Follow the customization loop

  1. Find the real file with pinchos config-path.
  2. Copy the current TOML into a temporary XDG_CONFIG_HOME root before editing it.
  3. Preserve unrelated tables and declaration order, then show the exact executable, arguments, paths, and environment names.
  4. Run XDG_CONFIG_HOME=<staging-root> pinchos validate, doctor, and run <item> against the staged file.
  5. After approval, promote only the reviewed diff if the live file is unchanged, then repeat the checks against the live path.
  6. Save the file and confirm the running app reloads the intended path.

The skill reference covers the seven supported item keys, ordered menu rows, cache behavior, and the read-only configuration boundary.

4 · Review commands before you add them

command boundary

Pinchos runs run, row actions, and dynamic menu commands with your permissions. Those commands are not sandboxed. validate and doctor do not approve command intent.

  • Ask for authorization before a command changes state, uses credentials, sends data, contacts a private service, or invokes a privileged tool.
  • Keep secrets out of TOML and use an existing login, keychain, or environment mechanism.
  • Reject curl | sh, remote script execution, eval, sudo, destructive commands, and broad file globs.
  • Set a practical Pinchos timeout for commands that contact a network or may take longer than a menu refresh should.

5 · Read the reference

The installed skill routes detailed schema and safety guidance to its bundled reference instead of copying the whole schema into every prompt.