Metadata-Version: 2.3
Name: ag-skill
Version: 0.1.6
Summary: Install curated AI agent skills into any repository
Author: Shariq Khan
Author-email: Shariq Khan <shariqnasir@outlook.com>
Requires-Dist: cryptography>=49.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: jsonschema>=4.26.0
Requires-Dist: keyring>=25.7.0
Requires-Dist: pyjwt>=2.13.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: typer>=0.26.8
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# ag-skill

![ag-skill logo](https://raw.githubusercontent.com/snk-learn/ag-skill/main/docs/images/Logo.png)

**A command-line tool for installing and managing AI engineering assets in any repository: skills, templates, and agent bundles.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

This README covers how to install and use the CLI for skills, templates, and agent bundles.

## Table of Contents

- [What ag-skill Does](#what-ag-skill-does)
- [Requirements](#requirements)
- [Install](#install)
- [Agent Templates](#agent-templates)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [CLI Help](#cli-help)
- [Common Examples](#common-examples)
- [Notes](#notes)
- [Docs](#docs)
- [License](#license)

## What ag-skill Does

With `ag-skill`, you can:

- List available skills
- Install one or more skills into the current repository
- Scaffold agent templates and install agent bundles (for example, `core-agents`)
- Select stack-aware bundle variants (`--backend`, `--frontend`) at install time
- Remove installed skills
- Upgrade installed skills
- Scaffold a custom skill
- Validate installed skills

## Requirements

- Python 3.11 or later
- One of [`uv`](https://docs.astral.sh/uv/), [`pipx`](https://pipx.pypa.io/), or `pip`
- A local repository you want to work in

## Install

`ag-skill` is published on [PyPI](https://pypi.org/project/ag-skill/). Install it with `uv` (recommended), `pipx`, or `pip`:

````powershell
uv tool install ag-skill
````

````powershell
pipx install ag-skill
````

````powershell
pip install ag-skill
````

### Install from source (latest unreleased changes)

To install directly from the GitHub repository instead of PyPI:

````powershell
uv tool install ag-skill --from git+https://github.com/snk-learn/ag-skill.git@main
````

### Verify installation

````powershell
ag-skill --help
````

If the command is not recognized after installation, restart the terminal and try again.

### Upgrading ag-skill

If installed from PyPI:

````powershell
uv tool upgrade ag-skill
````

````powershell
pip install --upgrade ag-skill
````

If installed from the GitHub repository, reinstall with `--force`:

````powershell
uv tool install ag-skill --from git+https://github.com/snk-learn/ag-skill.git@main --force
````

## Quick Start

Open a terminal in the repository where you want to use ag-skill.

### 1. List available skills

````powershell
ag-skill list
````

### 2. Install a skill into the current repository

````powershell
ag-skill install <skill-name>
````

Example:

````powershell
ag-skill install testing
````

### 3. Install an agent bundle (templates + skills)

````powershell
ag-skill add core-agents
````

Example with explicit stack selection:

````powershell
ag-skill add core-agents --backend python --frontend react
````

---

## Usage

Run all commands from the root of the repository you want to update.

### List skills

Show all skills available in the catalog.

````powershell
ag-skill list
````

Help:

````powershell
ag-skill list --help
````

### List bundles

Show all agent template bundles (e.g. `core-agents`) available in the catalog.

````powershell
ag-skill bundles
````

Help:

````powershell
ag-skill bundles --help
````

### Install skills

Install one or more catalog skills into the current repository.

````powershell
ag-skill install <skill-name>
````

Install multiple skills:

````powershell
ag-skill install <skill-one> <skill-two>
````

Install all available skills:

````powershell
ag-skill install --all
````

Install for a specific target:

````powershell
ag-skill install <skill-name> --target copilot
````

Force overwrite existing installed skills:

````powershell
ag-skill install <skill-name> --force
````

Install everything at once (all skills, all targets, overwriting existing ones):

````powershell
ag-skill install --all --target all --force
````

Help:

````powershell
ag-skill install --help
````

Supported install targets:

- `copilot`
- `claude`
- `cursor`
- `all`
- comma-separated target values

### Remove skills

Remove one or more installed skills.

````powershell
ag-skill remove <skill-name>
````

Remove multiple skills:

````powershell
ag-skill remove <skill-one> <skill-two>
````

Remove from a specific target:

````powershell
ag-skill remove <skill-name> --target all
````

Help:

````powershell
ag-skill remove --help
````

### Upgrade installed skills

Upgrade installed skills to the latest catalog version.

````powershell
ag-skill upgrade
````

Upgrade a specific target:

````powershell
ag-skill upgrade --target all
````

Help:

````powershell
ag-skill upgrade --help
````

### Add a custom skill

Scaffold a new custom skill in the repository.

````powershell
ag-skill add <skill-name>
````

Example:

````powershell
ag-skill add my-custom-skill
````

Specify a target:

````powershell
ag-skill add my-custom-skill --target copilot
````

Help:

````powershell
ag-skill add --help
````

## Agent Templates

`ag-skill` also ships the `core-agents` bundle, which scaffolds a templated
agent team for spec-to-ship workflows.

### Install the CLI

If you do not have `ag-skill` yet, install it first:

````powershell
uv tool install ag-skill
````

````powershell
pipx install ag-skill
````

````powershell
pip install ag-skill
````

### Install the agent templates

Run these commands from the root of the repository you want to update:

````powershell
ag-skill add core-agents
````

That uses the default stack pairing: `dotnet` for backend and `react` for
frontend.

Choose a different backend stack when needed:

````powershell
ag-skill add core-agents --backend python --frontend react
````

````powershell
ag-skill add core-agents --backend java --frontend react
````

````powershell
ag-skill add core-agents --backend go --frontend react
````

The bundle renders `ag-architect`, `ag-coder`, `ag-ui-developer`, and
`ag-tester` templates into the target repository using the selected stack.

It also installs `workflow.md` into the target agent directory (for example
`.github/agents/workflow.md` for Copilot target) so you can follow the
spec-to-ship sequence in the client project.

More detail is available in [docs/skills/core-agents-templates.md](https://github.com/snk-learn/ag-skill/blob/main/docs/skills/core-agents-templates.md).
For step-by-step client-project usage (agent selection, invocation order, and troubleshooting), see [Core Agents Workflow Usage Guide](https://github.com/snk-learn/ag-skill/blob/main/docs/templates/core-agents/workflow-usage.md).

### Validate installed skills

Validate installed skills against the supported spec.

````powershell
ag-skill doctor
````

Help:

````powershell
ag-skill doctor --help
````

### Show version

````powershell
ag-skill version
````

Help:

````powershell
ag-skill version --help
````

---

## CLI Help

### Top-level help

````powershell
ag-skill --help
````

### Command help

````powershell
ag-skill list --help
ag-skill bundles --help
ag-skill install --help
ag-skill remove --help
ag-skill upgrade --help
ag-skill add --help
ag-skill doctor --help
ag-skill version --help
````

---

## Common Examples

List skills:

````powershell
ag-skill list
````

List available bundles:

````powershell
ag-skill bundles
````

Install the `core-agents` bundle:

````powershell
ag-skill add core-agents
````

Install a skill:

````powershell
ag-skill install testing
````

Install multiple skills:

````powershell
ag-skill install testing docs ci
````

Install all skills:

````powershell
ag-skill install --all
````

Install all skills for all targets, overwriting existing ones:

````powershell
ag-skill install --all --target all --force
````

Remove a skill:

````powershell
ag-skill remove testing
````

Upgrade installed skills:

````powershell
ag-skill upgrade
````

Validate installed skills:

````powershell
ag-skill doctor
````

---

## Notes

- Run ag-skill inside the repository you want to update.
- Use `ag-skill --help` or `<command> --help` to see the latest supported options.
- The `list` command shows available skills; `bundles` shows available agent template packs.
- The `install` command installs catalog skills into a repository.
- The `add` command scaffolds a new custom skill or installs a bundle (e.g. `ag-skill add core-agents`).

---

## Docs

- [Core Agents Templates](https://github.com/snk-learn/ag-skill/blob/main/docs/skills/core-agents-templates.md)
- [Core Agents Workflow Usage Guide](https://github.com/snk-learn/ag-skill/blob/main/docs/templates/core-agents/workflow-usage.md)
- [Token Observability Skill Guide](https://github.com/snk-learn/ag-skill/blob/main/docs/skills/token-obserabilty.md)

---

## License

ag-skill is open source, released under the [MIT License](https://github.com/snk-learn/ag-skill/blob/main/LICENSE). Any use, distribution, or derivative work must credit ag-skill and reference its repository URL: <https://github.com/snk-learn/ag-skill>
