Skip to content

AGENTS.md

Latest commit

 

History

History
185 lines (132 loc) · 5.63 KB

AGENTS.md

File metadata and controls

185 lines (132 loc) · 5.63 KB
Raw

AGENTS.md

Guidelines for AI agents working in this repository.

Repository Overview

This repository contains Agent Skills for AI agents following the Agent Skills specification. Skills install to .agents/skills/ (the cross-agent standard). This repo also serves as a Claude Code plugin marketplace via .claude-plugin/marketplace.json.

Repository Structure

amigoscode-skills/
├── .claude-plugin/
│   ├── marketplace.json   # Claude Code plugin marketplace manifest
│   └── plugin.json        # Plugin manifest
├── skills/                # Agent Skills
│   └── skill-name/
│       └── SKILL.md       # Required skill file
├── CONTRIBUTING.md
├── LICENSE
└── README.md

Build / Lint / Test Commands

Skills are content-only (no build step). Verify manually:

  • YAML frontmatter is valid
  • name field matches directory name exactly
  • name is 1-64 chars, lowercase alphanumeric and hyphens only
  • description is 1-1024 characters

Run the bundled validator to check every skill at once:

bash validate-skills.sh

Agent Skills Specification

Skills follow the Agent Skills spec.

Required Frontmatter

---
name: skill-name
description: What this skill does and when to use it. Include trigger phrases.
---

Frontmatter Field Constraints

Field Required Constraints
name Yes 1-64 chars, lowercase a-z, numbers, hyphens. Must match dir.
description Yes 1-1024 chars. Describe what it does and when to use it.
license No License name (default: MIT)
metadata No Key-value pairs (author, version, etc.)

Name Field Rules

  • Lowercase letters, numbers, and hyphens only
  • Cannot start or end with hyphen
  • No consecutive hyphens (--)
  • Must match parent directory name exactly

Valid: infographic, linkedin-poster, x-card-generator Invalid: Infographic, -poster, linkedin--poster

Optional Skill Directories

skills/skill-name/
├── SKILL.md        # Required - main instructions (<500 lines)
├── references/     # Optional - detailed docs loaded on demand
├── scripts/        # Optional - executable code
└── assets/         # Optional - templates, data files

Writing Style Guidelines

Structure

  • Keep SKILL.md under 500 lines (move details to references/)
  • Use H2 (##) for main sections, H3 (###) for subsections
  • Use bullet points and numbered lists liberally
  • Short paragraphs (2-4 sentences max)

Tone

  • Direct and instructional
  • Second person ("You are an infographic generation expert")
  • Professional but approachable

Formatting

  • Bold (**text**) for key terms
  • Code blocks for examples and templates
  • Tables for reference data
  • No excessive emojis

Clarity Principles

  • Clarity over cleverness
  • Specific over vague
  • Active voice over passive
  • One idea per section

Description Field Best Practices

The description is critical for skill discovery. Include:

  1. What the skill does
  2. When to use it (trigger phrases)
  3. Related skills for scope boundaries
description: Generate "HOW X WORKS" educational infographic diagrams. Use when the user wants an infographic, a "how X works" diagram, or an educational visual for a backend or Java topic.

Claude Code Plugin

This repo also serves as a plugin marketplace. The manifest at .claude-plugin/marketplace.json lists all skills for installation via:

/plugin marketplace add amigoscode/skills
/plugin install amigoscode

See Claude Code plugins documentation for details.

Git Workflow

Branch Naming

  • New skills: feature/skill-name
  • Improvements: fix/skill-name-description
  • Documentation: docs/description

Commit Messages

Follow the Conventional Commits specification:

  • feat: add skill-name skill
  • fix: improve clarity in infographic
  • docs: update README

Pull Request Checklist

  • name matches directory name exactly
  • name follows naming rules (lowercase, hyphens, no --)
  • description is 1-1024 chars with trigger phrases
  • SKILL.md is under 500 lines
  • No sensitive data or credentials

Checking for Updates

When using any skill from this repository:

  1. Once per session, on first skill use, check for updates:

  2. Only prompt if meaningful:

    • 2 or more skills have updates, OR
    • Any skill has a major version bump (e.g., 1.x to 2.x)

  3. Non-blocking notification at end of response:

    ---
Skills update available: X Amigoscode skills have updates.
Say "update skills" to update automatically, or run `git pull` in your amigoscode-skills folder.

  4. If user says "update skills":

    • Run git pull in the amigoscode-skills directory
    • Confirm what was updated

Skill Categories

See README.md for the current list of skills. When adding new skills, follow the naming patterns of existing skills in the repo.