git:20260204.f59e220 to git:20261104.5e958b3

117 added, 171 removed. Audit A to B.

# Agent Skills - Development Guide

- This is the official skills repository for latestaiagents. It contains 67 professional skills and 10 slash commands for AI coding agents.

+ 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/ # All skills organized by audience

- │ ├── safety/ # Essential safety skills (5 skills)

- │ │ └── ai-safety-guardrails/

- │ │ ├── destructive-operation-guard/

- │ │ │ └── SKILL.md

- │ │ ├── migration-safety/

- │ │ ├── database-safety/

- │ │ ├── file-operation-safety/

- │ │ └── git-safety/

- │ ├── developer/ # Developer-focused skills (19 skills)

- │ │ ├── git-mastery/ # Git workflows (6 skills)

- │ │ ├── code-intelligence/ # AI coding (7 skills)

- │ │ └── debug-detective/ # Debugging (6 skills)

- │ ├── mlops/ # For architects/MLOps engineers (20 skills)

- │ │ ├── agent-architect/ # Multi-agent + LangGraph (13 skills)

- │ │ └── llmops-guardian/ # LLM operations (7 skills)

- │ ├── rag-architect/ # RAG systems (7 skills)

- │ └── security/ # Security skills (16 skills)

- │ ├── owasp-guardian/ # OWASP Top 10 (10 skills)

- │ └── common-security/ # Common security (6 skills)

- ├── commands/ # Slash commands (Claude Code only)

- │ ├── git-undo.md

- │ ├── resolve-conflict.md

- │ └── ... (10 total)

- ├── .claude-plugin/ # Plugin configuration

- │ ├── plugin.json # Main plugin metadata

- │ └── marketplace.json # Marketplace entries

- ├── CLAUDE.md # This file

- ├── README.md # User documentation

- └── LICENSE # MIT License

+ ├── 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` (10 of 16) | Byte-identical; edit `skills/` then copy |

+ | `plugins/rag-architect/skills` | `skills/rag-architect` | Separate, shorter write-ups; not synced (open question: consolidate) |

+ | `plugins/devops-sre`, `plugins/qa-testing`, `plugins/hr-people-ops` | none | Only exist in the plugin |

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

## Creating a New Skill

- ### Step 1: Choose the Right Category

+ ### 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 Structure

+ ### Step 2: Create the directory

```bash

- # For a new skill in an existing suite

- mkdir -p skills/developer/git-mastery/new-skill-name

- # For a new suite

- mkdir -p skills/developer/new-suite-name/first-skill-name

+ mkdir -p skills/<suite>/<skill-name>

```

- ### Step 3: Create SKILL.md

- Every skill MUST have a `SKILL.md` file with this exact format:

+ ### Step 3: Write SKILL.md

```markdown

---

name: skill-name-in-kebab-case

description: |

- Brief description of what this skill does. Include activation keywords.

+ What the skill does, in one or two sentences.

Use this skill when [specific trigger conditions].

- Activate when user mentions [keywords that should trigger this skill].

+ Activate when: keyword, keyword, keyword.

---

# Skill Title

- **Brief one-line summary of what this skill does.**

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

## When to Use

- - Bullet point 1

- - Bullet point 2

- - Bullet point 3

+ - ...

+ ## When NOT to Use

+ - ...

## Workflow

- ### Step 1: First Step

- Description and code examples...

+ ### Step 1: ...

- ### Step 2: Second Step

- Description and code examples...

+ ### Step 2: ...

## Best Practices

- 1. Best practice 1

- 2. Best practice 2

- 3. Best practice 3

+ 1. ...

+ ## References

+ - Official source: https://...

```

- ### Step 4: Skill Naming Conventions

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

- - **Skill name**: `kebab-case` (e.g., `merge-conflict-surgeon`)

- - **Directory name**: Same as skill name

- - **File name**: Always `SKILL.md` (uppercase)

+ - `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 5: Description Field Best Practices

+ ### Step 4: Content standards

- The `description` field in the YAML frontmatter is critical for auto-activation. Include:

+ - 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

- 1. **What the skill does** (first sentence)

- 2. **When to activate** (trigger conditions)

- 3. **Keywords** that should trigger this skill

+ ### Step 5: Register the suite

- Example:

- ```yaml

- description: |

- Systematic merge conflict resolution with context analysis.

- Use this skill when user has merge conflicts, git conflicts, or needs to resolve conflicting changes.

- Activate when: merge conflict, conflict resolution, git merge failed, resolve conflicts.

+ 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": ["./"]

+ }

```

- ## Creating a New Slash Command

+ 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"]`).

- ### Step 1: Create the File

+ 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.

- ```bash

- touch commands/new-command.md

- ```

+ ## Creating a Slash Command

- ### Step 2: Use This Format

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

```markdown

---

description: Brief description of what this command does

---

# /command-name

- One-line summary of the command.

+ One-line summary.

## What I Need

- Tell me:

- - Required input 1

- - Required input 2

+ - Required input

## Workflow

- ### Step 1: First Step

- ...

- ### Step 2: Second Step

- ...

- ## Quick Reference

- | Option | Description |

- |--------|-------------|

- | Option A | What it does |

- | Option B | What it does |

+ ### Step 1: ...

```

- ### Step 3: Naming Conventions

- - **File name**: `kebab-case.md` (e.g., `git-undo.md`)

- - **Command name**: Same as file name without `.md` (e.g., `/git-undo`)

- ## Updating marketplace.json

- When adding a new suite, add an entry to `.claude-plugin/marketplace.json`:

+ ## Validating

- ```json

- {

- "name": "suite-name",

- "source": "./skills/category/suite-name",

- "description": "Brief description of the suite.",

- "version": "1.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"

- }

+ ```bash

+ python3 scripts/validate.py # frontmatter, names, manifests, plugin copies, counts

+ claude plugin validate . # marketplace and root plugin

+ claude plugin validate plugins/<plugin>

```

- ## Content Guidelines

- ### DO

- - Use clear, actionable language

- - Include real code examples (TypeScript, bash, SQL)

- - Provide step-by-step workflows

- - Add safety warnings for destructive operations

- - Include "Best Practices" section

- - Use tables for quick reference

- ### DON'T

- - Use jargon without explanation

- - Skip code examples

- - Assume user knowledge

- - Forget safety considerations

- - Write walls of text without structure

- ## Safety Skills Requirements

- Skills in `skills/safety/ai-safety-guardrails/` MUST:

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

- 1. Use "Danger Levels" instead of "When to Use"

- 2. Include explicit confirmation protocols

- 3. Provide recovery procedures

- 4. Show exact impact before operations

- 5. Never proceed without user confirmation

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

- ## Testing Locally

+ ## Testing with the Skills CLI

```bash

- # Install all skills locally

- npx skills add ./ --all

- # Install specific category

- npx skills add ./skills/developer --all

- # Install specific suite

- npx skills add ./skills/developer/git-mastery --all

+ npx skills add ./ --list

+ npx skills add ./ --skill <skill-name>

```

## File Checklist

- Before committing a new skill:

- - [ ] `SKILL.md` exists with correct format

- - [ ] YAML frontmatter has `name` and `description`

- - [ ] Description includes activation keywords

- - [ ] Content has clear sections and examples

- - [ ] Code examples are correct and tested

- - [ ] Safety considerations addressed (if applicable)

- - [ ] `marketplace.json` updated (if new suite)

- - [ ] README.md updated (if new suite or category)

+ - [ ] `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

- - **Homepage**: https://github.com/latestaiagents/agent-skills

+ - GitHub: https://github.com/latestaiagents/agent-skills

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

## Version

- Current version: 1.0.0

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