Skip to main content

ag-skill

ag-skill logo

CLI to install and manage AI agent skills, Copilot templates, and workflow bundles in any repository.

Python 3.11+ License: Apache 2.0 Docs


ag-skill helps engineering teams standardize AI delivery by installing reusable skill packs and production-ready agent templates into existing repositories.

Best for:

  • Copilot and multi-agent workflow setup
  • Domain-Driven Design (DDD) aligned core agent bundles
  • Structured spec-to-ship delivery workflows
  • Prompt engineering and domain skill reuse
  • Installing templates and bundles consistently across projects

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

Table of Contents

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) that support DDD-centered, spec-to-ship execution
  • 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, pipx, or pip
  • A local repository you want to work in

Install

ag-skill is published on PyPI. Install it with uv (recommended), pipx, or pip:

uv tool install ag-skill
pipx install ag-skill
pip install ag-skill

Install from source (latest unreleased changes)

To install directly from the GitHub repository instead of PyPI:

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

Verify installation

ag-skill --help

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

Upgrading ag-skill

If installed from PyPI:

uv tool upgrade ag-skill
pip install --upgrade ag-skill

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

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

ag-skill list

2. Install a skill into the current repository

ag-skill install <skill-name>

Example:

ag-skill install testing

3. Install an agent bundle (templates + skills)

ag-skill add core-agents

Example with explicit stack selection:

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.

ag-skill list

Help:

ag-skill list --help

List bundles

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

ag-skill bundles

Help:

ag-skill bundles --help

Install skills

Install one or more catalog skills into the current repository.

ag-skill install <skill-name>

Install multiple skills:

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

Install all available skills:

ag-skill install --all

Install for a specific target:

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

Force overwrite existing installed skills:

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

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

ag-skill install --all --target all --force

Help:

ag-skill install --help

Supported install targets:

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

Remove skills

Remove one or more installed skills.

ag-skill remove <skill-name>

Remove multiple skills:

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

Remove from a specific target:

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

Help:

ag-skill remove --help

Upgrade installed skills

Upgrade installed skills to the latest catalog version.

ag-skill upgrade

Upgrade a specific target:

ag-skill upgrade --target all

Help:

ag-skill upgrade --help

Add a custom skill

Scaffold a new custom skill in the repository.

ag-skill add <skill-name>

Example:

ag-skill add my-custom-skill

Specify a target:

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

Help:

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:

uv tool install ag-skill
pipx install ag-skill
pip install ag-skill

Install the agent templates

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

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:

ag-skill add core-agents --backend python --frontend react
ag-skill add core-agents --backend java --frontend react
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. For step-by-step client-project usage (agent selection, invocation order, and troubleshooting), see Core Agents Workflow Usage Guide.

Validate installed skills

Validate installed skills against the supported spec.

ag-skill doctor

Telemetry

ag-skill includes commands for recording and reviewing local skill/agent run telemetry. All data stays in your repository under .ag-skill/telemetry/runs.jsonl — no external service required.

Because ag-skill runs outside Copilot/Claude/Cursor, token usage is self-reported using one of the observe sub-commands.

Important:

  • ag-skill observe only displays existing telemetry; it does not execute agents.
  • Run your agent first (for example ag-architect ...), then record after.
  • Use observe, stats, and dashboard only for review/reporting.

Record from VS Code Copilot Chat (auto-read transcript)

No pasting or piping needed — ag-skill finds the latest transcript automatically:

ag-skill observe from-copilot --skill ddd-aggregate-design --agent ag-architect --model gpt-4o --duration-ms 12400

Omit --skill to preview without recording. Tokens are estimated (Copilot Chat transcripts don't include usage data).

Record from Claude Code (exact token counts)

Claude Code session files include exact token counts, including cache hits:

ag-skill observe from-claude --skill ddd-aggregate-design --duration-ms 18500

ag-skill looks under ~/.claude/projects/<encoded-cwd>/ for the latest session. Omit --skill to preview without recording.

Record manually (stdin / file / inline)

Give ag-skill the response text and it estimates tokens automatically (1 token ≈ 4 chars). Pipe the agent's output straight in:

my-agent "design DDD aggregates for the order service" |
  ag-skill observe record --skill ddd-aggregate-design --agent ag-architect --model gpt-5 --response-stdin --duration-ms 12400

Or point at a file the tool already wrote:

ag-skill observe record --skill ddd-aggregate-design --agent ag-architect --model gpt-5 --response-file .\out\answer.md --duration-ms 12400

Or supply exact token counts if your platform's API reports usage:

ag-skill observe record --skill ddd-aggregate-design --agent ag-architect --model gpt-4o --prompt-tokens 3200 --completion-tokens 1800 --duration-ms 12400

View recent runs

ag-skill observe
ag-skill observe --tail 50
ag-skill observe -n 0        # show all

Aggregated stats

ag-skill stats

Generate an HTML dashboard

ag-skill dashboard
start .ag-skill/dashboard.html

For full details, options, and examples see docs/skills/telemetry.md.

Help:

ag-skill observe --help
ag-skill observe from-copilot --help
ag-skill observe from-claude --help
ag-skill observe record --help

Show version


---

## CLI Help

### Top-level help

````powershell
ag-skill --help

Command help

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:

ag-skill list

List available bundles:

ag-skill bundles

Install the core-agents bundle:

ag-skill add core-agents

Install a skill:

ag-skill install testing

Install multiple skills:

ag-skill install testing docs ci

Install all skills:

ag-skill install --all

Install all skills for all targets, overwriting existing ones:

ag-skill install --all --target all --force

Remove a skill:

ag-skill remove testing

Upgrade installed skills:

ag-skill upgrade

Validate installed skills:

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

📖 Full documentation site →


License

ag-skill is open source, released under the Apache License 2.0.

Metadata

Release files for ag-skill 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ag-skill 1.1.1
File Size Uploaded Provenance Actions
ag_skill-1.1.1.tar.gz 185.2 kB Without provenance Details for ag_skill-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ag-skill 1.1.1
File Interpreter ABI Platform Actions
ag_skill-1.1.1-py3-none-any.whl Python 3 none any Details for ag_skill-1.1.1-py3-none-any.whl

Total release size: 489.4 kB

Release files / ag_skill-1.1.1.tar.gz

Download URL ag_skill-1.1.1.tar.gz
Size 185.2 kB
Tags Source
SHA-256 checksum
How to use checksums
131594fdee36047167dafd6185442d56928599b384a57e78a411396c276b27db
BLAKE2b-256 checksum
How to use checksums
b662c678078762b494c55ac78cb96974dfe738b5b677fc7dd661f8f09eb9b062
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ag_skill-1.1.1-py3-none-any.whl

Download URL ag_skill-1.1.1-py3-none-any.whl
Size 304.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b9f535ef4984f2bafa29bc9af3b201614cca0e9d36f1251513488fe345d721ff
BLAKE2b-256 checksum
How to use checksums
d1f15a3391a967e9edcc88c4d4b1cce113a3fa57ee89794440966887686bbb94
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ag-skill 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page