agent-skills

Reusable AI skill definitions for version control, analytics workflows, and semantic layer design.

---

What This Is

Skills are structured instructions that AI agents load to perform specialized tasks consistently. Instead of re-explaining conventions in every session (commit message format, branching strategy, PR hygiene, Python tooling preferences), skills encode them once and apply everywhere.

This repository contains skills designed for data analysts and analytics engineers who work with AI coding assistants. The conventions here are tool-agnostic: they work in any IDE (Cursor, VS Code, Zed, JetBrains), with any AI model, and across any git-based workflow.

The skills follow the Agent Skills standard (SKILL.md format with YAML frontmatter) and are installable as a Claude Code plugin. They are equally readable as plain markdown by any LLM or human.

---

Prerequisites

System requirements

• Git (2.30+) with a configured identity:

  git config --global user.name "Your Name"
  git config --global user.email "you@example.com"

• GitHub CLI (gh), authenticated and configured for SSH:

  gh auth login
  gh auth setup-git

• SSH key registered with GitHub, typically at ~/.ssh/id_ed25519 or ~/.ssh/id_rsa. Generate one if needed:

  ssh-keygen -t ed25519 -C "you@example.com"
  gh ssh-key add ~/.ssh/id_ed25519.pub --title "my-machine"

• Platform: Linux (Ubuntu or Fedora) or macOS. The conventions are OS-agnostic but the documented commands assume a Unix shell.

Recommended tools

• Cursor or any AI-enabled editor
• Poetry for Python dependency management
• Claude Code for plugin installation (optional; skills are usable without it)

---

Installation

As a Claude Code plugin (recommended for Claude Code users)

Register the marketplace and install:

/plugin marketplace add aleberriz/agent-skills
/plugin install core-skills@agent-skills

After installation, skills activate automatically based on context. Mention git, commits, branching, PRs, or any covered topic and the relevant skill loads.

In Cursor IDE

Symlink skills into your global ~/.cursor/skills/ directory (recommended) or copy them into a project's .cursor/skills/ directory.

Global symlink (recommended): the symlink points at the live repo, so every git pull on this repo automatically updates the installed skill — no re-copy needed.

mkdir -p ~/.cursor/skills
ln -s "$(pwd)/plugins/core-skills/skills/process-git" ~/.cursor/skills/process-git

Per-project copy (useful when you want a pinned version or don't have this repo checked out locally):

mkdir -p /path/to/your-project/.cursor/skills
cp -r plugins/core-skills/skills/process-git /path/to/your-project/.cursor/skills/

# Install an entire category
cp -r plugins/core-skills/skills/process-* /path/to/your-project/.cursor/skills/

When using a copy rather than a symlink, re-run the cp command after pulling updates from this repo to keep the installed skill current.

In any other tool (AGENTS.md reference)

Reference the skills from your project's AGENTS.md:

## Conventions

This project follows the git workflow conventions defined in
[agent-skills/process-git](https://github.com/aleberriz/agent-skills/tree/main/plugins/core-skills/skills/process-git).

Any AI agent that reads AGENTS.md (Cursor, GitHub Copilot, OpenAI Codex, Google Jules, Aider, Zed, JetBrains Junie) will follow the link and apply the conventions.

In a team project (Claude Code)

Add to the project's .claude/settings.json to make the skills available automatically for everyone on the team:

{
  "extraKnownMarketplaces": {
    "agent-skills": {
      "source": {
        "source": "github",
        "repo": "aleberriz/agent-skills"
      }
    }
  },
  "enabledPlugins": ["core-skills@agent-skills"]
}

---

The Workflow

Creating a new repository

cd ~/repos
gh repo create <owner>/<repo-name> --public --clone -d "Short description"
cd <repo-name>

Commit the initial LICENSE and .gitignore directly on main:

git add LICENSE .gitignore
git commit -m "chore: initialize repository"
git push -u origin main

Then branch for all remaining setup:

git checkout -b chore/init-config

On this branch, add: README.md, AGENTS.md, project configuration (.gitignore extensions, pyproject.toml, .cursor/rules/, etc.). Open a PR, merge, and clean up:

git push -u origin chore/init-config
gh pr create --title "chore: add project configuration and documentation" --body "..."
# After merge:
git checkout main && git pull --ff-only && git branch -d chore/init-config && git fetch --prune

Working on a branch

git checkout -b feat/my-new-feature
# ... work ...
git add -A && git commit -m "feat: add my new feature"
git push -u origin feat/my-new-feature
gh pr create --title "feat: add my new feature" --body "..."

After merge

git checkout main
git pull --ff-only
git branch -d feat/my-new-feature
git fetch --prune

See the process-git skill for the full specification including commit format, branching model, PR description conventions, and merge strategy.

---

Skill Catalog

Skills use prefixed names that sort alphabetically into three groups, making it easy to browse, glob, and cherry-pick by category.

process-* (cross-cutting)

Skill	Status	Description
process-git	Active	Branching model, conventional commits, PR hygiene, post-merge cleanup, repo initialization
process-scaffold	Planned	Full repo scaffolding recipes for analytics and data projects

tooling-* (languages and ecosystems)

Skill	Status	Description
tooling-python	Planned	Poetry, Jupyter, plotnine/Plotly, pandas conventions
tooling-sql	Planned	Dialect-aware SQL formatting, naming, performance patterns

analytics-* (domain knowledge)

Skill	Status	Description
analytics-descriptive	Planned	EDA, analysis structure, stakeholder communication, dashboards
analytics-experimentation	Planned	A/B testing, power analysis, sequential testing, result interpretation
analytics-ml	Planned	Feature engineering, model evaluation, forecasting, deployment
analytics-semantic-layer	Planned	AI context fields, topic scoping, metric governance (OSI-aligned)

Complementary skills (external)

These skills are maintained by their respective projects and cover tool-specific mechanics. The skills in this repository encode the judgment layer on top.

Skill	Maintained by	Description
omni-claude-skills	Omni	Omni REST API: model exploration, querying, content building, admin
Anthropic example skills	Anthropic	Reference implementations for document creation, design, development

---

Design Principles

• Vendor-agnostic content: Skills are plain markdown with YAML frontmatter. The SKILL.md format is readable by any LLM. The .claude-plugin/ structure enables Claude Code installation but is not required for use.
• Explain the why: Instructions explain reasoning, not just rules. AI models perform better when they understand intent rather than following rigid constraints.
• Practitioner-grade: Written for working analysts and engineers, not as tutorials. Concrete examples, linked references, opinionated defaults.
• Composable: Skills are independent and can be used individually or together. The analytics-semantic-layer skill builds on top of omni-claude-skills; the process-scaffold skill builds on top of process-git. Each works alone.

---

References

• Conventional Commits v1.0.0
• Agent Skills specification
• Agent Skills skill creator
• Open Semantic Interchange (OSI)
• omni-claude-skills

---

About

Built by Alejandro Berrizbeitia, Senior Data Analyst at Kit.