a-i--skills

# Repository Guidelines

Global policy: /Users/4jp/AGENTS.md applies and cannot be overridden.

This repository is a collection of example Claude skills. Each skill is self-contained in its own folder and is documented by a `SKILL.md` file with YAML frontmatter. Use this guide when adding or updating skills.

## Project Structure & Module Organization
- Top-level docs: `README.md` (overview), `agent_skills_spec.md` (skill schema reference), and `THIRD_PARTY_NOTICES.md`.
- Skill directories: one folder per skill (kebab-case name), each with a `SKILL.md` and optional `references/`, `scripts/`, `assets/`, or `ooxml/` subfolders.
- Document skills: `document-skills/` mirrors the `docx/`, `pdf/`, `pptx/`, and `xlsx/` skills with more extensive scripts and schemas.
- Generated collections: `collections/example-skills.txt` and `collections/document-skills.txt` (one path per line).
- Agent link dirs: `skills/`, `.codex/skills`, `.claude/skills`, and `extensions/gemini/*/skills` are generated by the refresh script.

## Build, Test, and Development Commands
There is no repo-wide build or test runner. Run scripts per skill when needed.

Examples:
- `python3 document-skills/pdf/scripts/check_bounding_boxes_test.py` (runs a small unittest)
- `pip install -r mcp-builder/scripts/requirements.txt`
- `pip install -r slack-gif-creator/requirements.txt`
- `python3 scripts/refresh_skill_collections.py` (regenerates collections and link dirs)
- `python3 scripts/validate_skills.py --collection example --unique`
- `python3 scripts/refresh_skill_collections.py --mode symlink` (optional symlink mode)
- `python3 scripts/validate_generated_dirs.py` (ensures bundles are copied and in sync)

## Coding Style & Naming Conventions
- Skills are Markdown-first. Keep instructions in `SKILL.md` with YAML frontmatter:
  - `name:` lowercase kebab-case and should match the folder name.
  - `description:` short, task-focused, and written as a sentence.
- Keep examples concise and actionable; prefer ASCII unless the content requires otherwise.
- Place executable helpers under `scripts/` and keep them self-contained.

## Testing Guidelines
- No shared testing framework or coverage target is enforced.
- If you add scripts, include a simple, runnable smoke check (command and expected behavior) in the skill instructions or a nearby README.

## Commit & Pull Request Guidelines
- Commit messages are short, imperative, and often include a PR reference in parentheses (e.g., "Clarify Claude Code installation in README.md (#20)").
- PRs should summarize affected skills, link relevant issues/docs, and call out any new dependencies. Update `README.md` if you add or remove skills from the curated lists.
- Regenerated link directories and collections are committed artifacts; run the refresh script and include them in skill-change PRs.

## Security & Configuration Tips
- Do not commit secrets. Reference environment variables in scripts when external credentials are required.
- Keep third-party attributions updated in `THIRD_PARTY_NOTICES.md` when adding external assets or data.