AGENTS.md

This file is guidance for agentic coding tools working in this repository. Follow it first, then defer to repo docs and the Agent Skills specification.

Repository purpose

• This repo stores reusable Agent Skills aligned to https://agentskills.io.
• Skills are Markdown-first, with optional scripts, references, and assets.
• Treat this repo as documentation + examples, not a production service.

Sources of truth

• PRD.md for goals, constraints, and acceptance criteria.
• CONTRIBUTION.md for contribution workflow and standards.
• Agent Skills spec: https://agentskills.io/specification
• Best practices: https://agentskills.io/skill-creation/best-practices

Build, lint, and test commands

There is no app build, lint, or unit test suite in the root repo. Validation is done per-skill using the Agent Skills reference validator.

Skills validation (primary check)

Setup (submodule + tools):

git submodule update --init --recursive
cd third_party/agentskills/skills-ref
uv sync
source .venv/bin/activate

Validate a single skill (preferred single-target check):

skills-ref validate /path/to/skill

Examples for this repo:

skills-ref validate ./sample-skill
skills-ref validate ./sample-skill-advanced

If skills-ref is not on PATH, use the venv executable:

third_party/agentskills/skills-ref/.venv/bin/skills-ref validate ./sample-skill

Code style and structure guidelines

Skill directory layout

• Each non-sample skill lives under skills/ and is a folder containing a required SKILL.md.
• Optional folders: scripts/, references/, assets/.
• Keep the layout shallow and consistent with sample skills.

SKILL.md frontmatter rules (required)

• name must match the folder name.
• Use lowercase letters, numbers, and hyphens only.
• No leading/trailing hyphens, no consecutive hyphens.
• description must be clear about what the skill does and when to use it.
• Optional fields must follow the spec (license, compatibility, metadata).

SKILL.md body content

• Write concise, procedural instructions.
• Provide defaults rather than listing many options.
• Focus on project-specific knowledge, not generic advice.
• Include examples or templates when output format matters.

Progressive disclosure

• Keep SKILL.md under 500 lines and under 5,000 tokens.
• Move extended details into references/.
• Use assets/ for templates and static resources.
• Use scripts/ for executable logic that should be reused.
• In SKILL.md, tell the agent exactly when to load each file.

File references

• Use relative paths from the skill root (e.g., references/REFERENCE.md).
• Keep references one level deep from SKILL.md.

Naming conventions

• Skill folders: lowercase letters, numbers, hyphens only.
• Files: prefer lowercase with hyphens or underscores; be consistent within a skill.
• Avoid spaces in file and folder names.

Formatting

• Markdown is the primary format; keep it clean and readable.
• Use fenced code blocks with a language tag when possible.
• Keep line lengths reasonable for readability.

Scripts (if added)

• Bash scripts should start with #!/usr/bin/env bash and set -euo pipefail.
• Provide clear usage instructions and error messages.
• Keep scripts self-contained or document dependencies.
• Prefer deterministic output for validation steps.

Error handling

• Fail fast in scripts with helpful messages.
• Avoid silent failures; log what went wrong and how to fix it.
• Validate inputs before performing destructive steps.

Types and imports

• If writing Python scripts, prefer explicit imports and small, testable functions.
• Keep dependencies minimal and document any non-standard requirements.
• Type hints are encouraged for non-trivial scripts.

Contribution workflow expectations

• Use pull requests for all changes.
• Keep commits concise and purpose-driven.
• Include validation results in PR descriptions.

Files to treat as authoritative

• PRD.md
• CONTRIBUTION.md
• README.md
• sample-skill/ and sample-skill-advanced/ as canonical examples

Cursor or Copilot rules

• No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found.

When in doubt

• Follow the Agent Skills specification first.
• Use the sample skills as the reference pattern.
• Keep skills concise, validated, and easy to discover.