AGENTS.md

Guidelines for AI agents working in this repository.

Repository overview

Open-source Agent Skills that audit sales call transcripts and CRM exports against per-GTM-motion rubrics. No Zime product coupling: every skill runs standalone, no API keys, no gating, no data leaves the user's machine. Skills install to .agents/skills/ (the cross-agent standard) and also work under .claude/skills/.

• Name: zime-gtm-skills
• GitHub: zime-ai/zime-gtm-skills
• Maintained by: Zime
• License: MIT

Repository structure

zime-gtm-skills/
├── .claude-plugin/
│   ├── marketplace.json       # /plugin marketplace add zime-ai/zime-gtm-skills
│   └── plugin.json
├── skills/
│   └── skill-name/
│       ├── SKILL.md          # required
│       ├── references/       # optional, the rubric lives here
│       ├── assets/           # optional, synthetic sample transcript/CSV
│       └── evals/            # optional, evals.json, declarative for now
├── validate-skills.sh         # local, zero-dep frontmatter/layout check
├── CONTRIBUTING.md
├── MAINTAINING.md              # process + decisions, for picking this repo back up
├── ROADMAP.md                   # what's built, what's next
├── LICENSE
└── README.md

Frontmatter contract

SKILL.md stays under 500 lines. Move detail into references/. references/, scripts/, assets/, evals/ are one level deep, no nested reference chains.

Validate

./validate-skills.sh                        # local, seconds, zero deps
./scripts/check-docs-sync.sh                # README count/table vs skills/, zero deps
python3 scripts/scan-content.py             # content-level leak/injection scan, zero deps
scripts/skillspector-gate.sh all         # static security scan (needs `skillspector` on PATH), or pass a base ref for changed skills only

CI additionally runs the upstream spec's skills-ref validate on every PR, pinned to a commit (see .github/workflows/validate.yml) since it isn't published to PyPI.

tests/run-checks-tests.sh runs the above three against deliberately broken fixtures (missing frontmatter, un-ignored private dirs, a leaked home path, an injection pattern, ...) so a CI failure has been shown to catch something, not only assumed to. Run it after touching any validator.

scripts/check-pr-diff-identity.py <base> <head> is different from the three above: it's diff-scoped, not tree-scoped, and runs automatically after scripts/pr-prep.sh opens a PR rather than before. See the operator-identity rule above.

Rule registry

Every automated check enforces a named rule, so a CI failure line points at what to fix, not just which script ran.

The two hard content rules

1. Every finding in a transcript-mode audit cites a quote or timestamp. An uncited finding doesn't ship: this is the trust bar the whole repo is built on.
2. Never expose anything that isn't already customer-visible in the Zime product. Checklist titles and question text are customer-visible and fine to draw on; internal scoring weights, thresholds, model configuration, and customer/account data are not. See MAINTAINING.md for the authoring process and how this gets enforced.

Building several skills at once? See MAINTAINING.md's "Building skills at scale" for the worktree-per-skill and create-validate-iterate flow.

Evals

Each skill may carry evals/evals.json: declarative test cases (prompt + sample file + expected expectations). They are not run in CI yet. See EVALS.md for the full methodology: the three eval tiers, why format compliance and insight recall are reported as two separate metrics rather than one blended number, and where a human is required versus where nothing is. Treat evals as the source of truth for "does this skill work," not the skills-ref/validate-skills.sh structural checks, which only catch frontmatter and layout errors.

Two dimensions: stage, initiative

Skills cover deal stage and initiative as ordinary, flat skills (zime:dimension: stage or initiative in frontmatter), never nested under a skills/stage/ or skills/initiative/ directory, since that breaks the install command above and both validators. A third axis, vertical-context (a reference pack per industry any other skill can load on request), was pulled off main before public launch pending domain-expert review. See MAINTAINING.md's "Two dimensions" and "Deferred work" sections, and the vertical-context branch.