ag-skill 1.0.1

Install curated AI agent skills into any repository

ag-skill

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

---

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

Table of Contents

• What ag-skill Does
• Requirements
• Install
• Agent Templates
• Quick Start
• Usage
• Telemetry
• CLI Help
• Common Examples
• Notes
• Docs
• 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, 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 →

• Core Agents Templates
• Core Agents Workflow Usage Guide
• Token Observability Skill Guide
• Local Telemetry — observe, stats, dashboard

---

License

ag-skill is open source, released under the MIT License. Any use, distribution, or derivative work must credit ag-skill and reference its repository URL: https://github.com/snk-learn/ag-skill