agent-skills: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

Overview

This repository contains official SiteGPT skills for AI agents. Skills follow the Agent Skills format used by the skills CLI and skills.sh.

Structure

skills/
  {skill-name}/
    SKILL.md
    commands/ (optional)
    playbooks/ (optional)

Commands

npm test
npx skills add . --list

Run npm test before committing changes.

Skill Rules

• SKILL.md must include YAML frontmatter with name, description, license, and metadata.version.
• The name must match the skill directory name.
• Use lowercase kebab-case skill names.
• The description is the trigger text agents see before loading the full skill, so include what the skill does and when to use it.
• Keep SKILL.md focused on agent behavior and core workflows.
• commands/ and playbooks/ are optional. Use them only when a skill is large enough that splitting genuinely helps; otherwise a single self-contained SKILL.md (up to 1000 lines) is fine and avoids drift.
• Do not include secrets, credentials, private customer data, or environment-specific tokens.

Source Of Truth For sitegpt-cli

The sitegpt-cli skill is synced, not authored here. Its canonical source is the SiteGPT product repo at public/agents/sitegpt-cli-skill.md (the file served at https://sitegpt.ai/agents/sitegpt-cli-skill.md and digest-verified there). To change this skill, edit it in the product repo, then copy the body here under this repo's frontmatter and bump the version. Do not edit skills/sitegpt-cli/SKILL.md directly or re-split it into commands//playbooks/ — that re-introduces the exact drift this consolidation removed.

Versioning

This repository uses manual releases.

• package.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json, and the root plugin.json (the Agent Plugins manifest) carry the RELEASE version and must match (validate-skills.mjs checks).
• Each SKILL.md metadata.version tracks that skill's own content: bump it when the skill changes, leave it alone when it does not. A release version ahead of an unchanged skill's version is expected in a multi-skill repo.
• sitegpt-cli is the exception either way: its version follows its canonical source in the product repo (see above) and only moves on a sync.
• Update CHANGELOG.md when making release commits.
• Use release commit messages like chore: release 0.1.2.
• Create a matching Git tag such as v0.1.2.
• GitHub Releases are optional unless a packaged archive is needed.