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
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:
copilotclaudecursorall- 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 observeonly displays existing telemetry; it does not execute agents.- Run your agent first (for example
ag-architect ...), then record after. - Use
observe,stats, anddashboardonly 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 --helpor<command> --helpto see the latest supported options. - The
listcommand shows available skills;bundlesshows available agent template packs. - The
installcommand installs catalog skills into a repository. - The
addcommand scaffolds a new custom skill or installs a bundle (e.g.ag-skill add core-agents).
Docs
- 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 Apache License 2.0.
Metadata
Release files for ag-skill 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ag_skill-1.1.0.tar.gz | 184.5 kB | Without provenance | Details for ag_skill-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ag_skill-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for ag_skill-1.1.0-py3-none-any.whl |
Total release size: 488.3 kB
Release files / ag_skill-1.1.0.tar.gz
| Download URL | ag_skill-1.1.0.tar.gz |
|---|---|
| Size | 184.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
80a4bca4634d7a7686668fded296789e9b4266fd977a973411c00d10e10608f2
|
|
BLAKE2b-256 checksum How to use checksums |
7a2f6007e025bbfe1a6c681153b02948c78452605a9977cba9a8dbd26517923b
|
| 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.0-py3-none-any.whl
| Download URL | ag_skill-1.1.0-py3-none-any.whl |
|---|---|
| Size | 303.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cb1fe163cecfca8ffc2432d9f8c8e323bc7b2b081b38288ac8210262f6983f9d
|
|
BLAKE2b-256 checksum How to use checksums |
09e7d45886ab91687a7c44e69d3b5ddc31bd392f3e559f5c66dd3541177b8ca3
|
| 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.0
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.