Repository Guidelines

Project Structure & Module Organization

• skills/ holds each skill in its own folder (kebab-case). Each skill has a SKILL.md file with YAML frontmatter (name, description) and Markdown guidance.
• Some skills include reference files alongside the SKILL.md (e.g. skills/agents-md/references/).
• Top-level files: README.md (overview and install docs).

Install / Development Commands

Primary install (recommended)

npx skills add mblode/agent-skills -g

Installs all skills at user level via the skills CLI (see the deploy chain below). Without -g the CLI installs into the current project instead. Works with Claude Code, Codex, Cursor, and OpenCode.

Install a single skill:

npx skills add mblode/agent-skills -g --skill tidy -y

Local dev: symlink hot-swap

For editing skills in place without reinstalling:

# One-time: symlink the repo's skills folder into the deploy target
ln -s /path/to/agent-skills/skills/<name> ~/.claude/skills/<name>

Changes to the repo files take effect immediately, with no re-install needed. Unlink with unlink ~/.claude/skills/<name> when done.

The deploy chain: skills add writes the content once to ~/.agents/skills/<name>/. Agents that read that canonical path directly, which is every agent whose skillsDir is .agents/skills (Codex, Cursor, and most others), need nothing further; the CLI calls them universal and installs there rather than into ~/.codex/skills or ~/.cursor/skills. Claude Code reads .claude/skills, so it alone gets a relative symlink, ~/.claude/skills/<name> -> ../../.agents/skills/<name>. Editing this repo changes none of them until you reinstall or symlink the folder directly.

Smoke-test

Confirm files landed correctly after install:

ls ~/.claude/skills/tidy/
# Expected: SKILL.md (plus any references/ folder)

For a full install smoke-check:

ls ~/.claude/skills/ | sort

Other repositories may contribute installed skills. Compare each owned folder recursively with its source; a directory listing alone does not establish parity.

Coding Style & Naming Conventions

• Files are Markdown-first, with supporting scripts and evaluation fixtures.
• No em dashes anywhere (skill bodies, descriptions, READMEs, commits). Restructure with commas, colons, periods, or parentheses; don't substitute a spaced hyphen.
• When detail is needed, add a focused reference file rather than expanding SKILL.md.

Skill Authoring

Every mechanical constraint (frontmatter limits, body length, reference chains, TOCs, kebab-case, rule-count reconciliation, README bullets) is enforced by the validator and stated nowhere else:

skills/agent-skills-creator/scripts/validate.sh skills/<name>
skills/agent-skills-creator/scripts/validate.sh --all

For the judgement a script cannot make (what to include, how prescriptive to be, when an absolute earns its place), run the agent-skills-creator skill.

Verification

Run the validator on every skill you touch, and python3 -m unittest discover -s maintenance/tests when changing the validation protocol. CI (.github/workflows/validate.yml) runs validate.sh --all and the unit tests on every pull request and push to main. Authored scenarios validate structurally only; behavioral evidence (with and without the skill) requires separate isolated runs, as agent-skills-creator describes. Compare the full installed skill folder when install behavior changes. There is no doctor command or feature map; the validator is the only automated proof, so a prose change is unverified until someone runs its scenarios.

Gotchas

• Reference files are only loaded when explicitly listed in the SKILL.md; dropping a file in the folder is not enough.
• The cp -R skills/* ~/.claude/skills/ approach bypasses the ~/.agents/skills symlink chain. Use npx skills add instead.

Commit & Pull Request Guidelines

• Commit messages: short, imperative, sentence case (e.g., "Add tidy skill").
• PRs: brief summary, list of skills changed/added, README updates (especially when adding a new skill).
• When adding reference files, note how they are used by the corresponding SKILL.md.

Maintenance

• When adding or removing a skill, add or remove its bullet under the matching category heading in README.md.
• When renaming folders or reference files, grep all SKILL.md files for stale paths.
• Verify counts and bullets with skills/agent-skills-creator/scripts/validate.sh --all. Don't count with ls skills/ | wc -l: git leaves empty directories behind when a skill moves out, which inflates it.