CLAUDE.md git:20261104.5b4636cB

Immutable. This exact content never changes and is served at /api/v1/blob/463b930d3ea8b1de.

# Agent Skills - Development Guide

This is the skills repository for latestaiagents: 109 skills in 17 suites under `skills/`, 7 Claude Code plugins under `plugins/`, and 10 root slash commands. Counts come from `python3 scripts/validate.py`; update them from its output, never by hand.

## Project Structure

```
agent-skills/
├── skills/                      # Canonical skills, organized by audience
│   ├── safety/ai-safety-guardrails/
│   ├── developer/{git-mastery,code-intelligence,debug-detective}/
│   ├── mlops/{agent-architect,llmops-guardian}/
│   ├── rag-architect/
│   ├── security/{owasp-guardian,common-security}/
│   ├── mcp-mastery/
│   ├── messages-api-features/   # Claude API features (formerly claude-4-6-features)
│   ├── claude-agent-sdk/        # plugin name: agent-sdk
│   ├── skills-authoring/
│   ├── evals/
│   ├── design-taste/
│   ├── growth-seo/
│   └── video-motion/
├── plugins/<plugin>/            # Claude Code plugins
│   ├── .claude-plugin/plugin.json
│   ├── .mcp.json
│   ├── commands/
│   └── skills/<group>/<skill>/SKILL.md
├── commands/                    # Root slash commands (latestaiagents-full)
├── scripts/validate.py          # Repository checks
├── .claude-plugin/
│   ├── plugin.json              # Root plugin (latestaiagents-full)
│   └── marketplace.json         # Marketplace "latestaiagents"
├── CHANGELOG.md
├── RELEASING.md
├── CLAUDE.md
└── README.md
```

## Canonical Sources

`skills/` is the canonical location for every skill that appears in both trees. Plugins must ship files inside their own directory (Claude Code rejects component paths that leave the plugin root, and warns that it does not read symlinked local sources), so plugins carry copies:

| Plugin copy | Canonical source | Rule |
|-------------|------------------|------|
| `plugins/developer-toolkit/skills` | `skills/developer` | Byte-identical; edit `skills/` then copy |
| `plugins/agent-architect/skills` | `skills/mlops/agent-architect` | Byte-identical; edit `skills/` then copy |
| `plugins/security-guardian/skills` | `skills/security` (all 16) | Byte-identical; edit `skills/` then copy |
| `plugins/rag-architect/skills` | `skills/rag-architect` | Byte-identical; edit `skills/` then copy |
| `plugins/devops-sre`, `plugins/qa-testing`, `plugins/hr-people-ops` | none | Only exist in the plugin |

`scripts/validate.py` fails if a plugin copy differs from its canonical file.

## Creating a New Skill

### Step 1: Choose the suite

Put the skill in an existing suite under `skills/` when one fits. Create a new suite only for a distinct audience or topic, and add a marketplace entry for it (Step 5).

### Step 2: Create the directory

```bash
mkdir -p skills/<suite>/<skill-name>
```

### Step 3: Write SKILL.md

```markdown
---
name: skill-name-in-kebab-case
description: |
  What the skill does, in one or two sentences.
  Use this skill when [specific trigger conditions].
  Activate when: keyword, keyword, keyword.
---

# Skill Title

**One-line summary of what this skill does.**

## When to Use

- ...

## When NOT to Use

- ...

## Workflow

### Step 1: ...

### Step 2: ...

## Best Practices

1. ...

## References

- Official source: https://...
```

Frontmatter rules (checked by `scripts/validate.py`, limits from the Agent Skills docs):

- `name` matches the directory name: lowercase letters, digits, hyphens; at most 64 characters; must not contain "claude" or "anthropic"
- `description` is at most 1,024 characters, written in third person, and says both what the skill does and when to use it

### Step 4: Content standards

- Verify every API name, CLI flag, package name, and install command against official docs or the project's own repository, and list those sources under `## References`
- No invented APIs, install counts, benchmark or performance claims, or unsourced percentages. Label example arithmetic as hypothetical
- No model-version claims in prose. In code, read model IDs from config (`process.env.ANTHROPIC_MODEL`) and point to the provider's models page
- For fast-changing facts (tool versions, crawler names, platform specs), say "as documented at the time of writing" and tell the reader where to re-check
- When unsure, say less
- Safety skills in `skills/safety/ai-safety-guardrails/` must include confirmation protocols, recovery procedures, and an impact preview before destructive operations

### Step 5: Register the suite

Add an entry to `.claude-plugin/marketplace.json` and add the suite path to the root `.claude-plugin/plugin.json` `skills` list:

```json
{
  "name": "suite-name",
  "source": "./skills/suite-name",
  "description": "What it covers. N skills.",
  "version": "2.0.0",
  "author": { "name": "latestaiagents" },
  "homepage": "https://github.com/latestaiagents/agent-skills",
  "repository": "https://github.com/latestaiagents/agent-skills",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "category": "Category Name",
  "skills": ["./"]
}
```

The `skills` field is required. Claude Code scans only `<plugin root>/skills/<name>/SKILL.md` by default, so an entry without it installs with zero skills. Use `["./"]` for a flat suite and one path per sub-suite for a category (for example `["./git-mastery", "./code-intelligence"]`).

Plugin names cannot start with `claude-`, `anthropic-`, or `cc-plugin-` (`claude plugin validate` rejects them). When renaming a plugin, add the old name to the top-level `renames` map.

## Creating a Slash Command

Create `commands/<name>.md` (or `plugins/<plugin>/commands/<name>.md`):

```markdown
---
description: Brief description of what this command does
---

# /command-name

One-line summary.

## What I Need

- Required input

## Workflow

### Step 1: ...
```

## Validating

```bash
python3 scripts/validate.py        # frontmatter, names, manifests, plugin copies, counts
claude plugin validate .           # marketplace and root plugin
claude plugin validate plugins/<plugin>
```

`claude plugin validate .` warns that this `CLAUDE.md` is not loaded as plugin context; that is expected.

To confirm Claude Code actually discovers the skills, install into a throwaway config directory as described in [RELEASING.md](RELEASING.md).

## Testing with the Skills CLI

```bash
npx skills add ./ --list
npx skills add ./ --skill <skill-name>
```

## File Checklist

- [ ] `SKILL.md` frontmatter has `name` (matching the directory) and `description`
- [ ] Facts verified; `## References` lists the sources
- [ ] No model-version claims, invented numbers, or unverified install commands
- [ ] Plugin copies updated if you edited a synced skill
- [ ] Marketplace entry and root `plugin.json` updated for a new suite
- [ ] README tables and counts updated from `scripts/validate.py`
- [ ] CHANGELOG `[Unreleased]` entry added

## Repository URLs

- GitHub: https://github.com/latestaiagents/agent-skills
- Issues: https://github.com/latestaiagents/agent-skills/issues

## Version

Current version: 2.0.0. See [CHANGELOG.md](CHANGELOG.md) and [RELEASING.md](RELEASING.md).