Guide · Agent skill
How to use the Google Workspace Admin Reports agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The gws-admin-reports skill teaches an AI agent how to use the gws command-line tool to read Google Workspace admin reporting data. It covers audit logs of account activity, such as Admin console and Google Drive events, plus usage reports for the whole customer account, per entity and per user. This guide explains what the skill does, how to install it, how to ask for reports in plain language, and what you need before it will work.
Google Workspace Admin Reportsgoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install the gws tool. Install the gws command-line tool (Google Workspace CLI) on the machine where your agent runs.
- 2Configure authentication. Set up Google Workspace authentication through the gws shared skill at ../gws-shared/SKILL.md, using an account with administrator access.
- 3Download and unzip the skill. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use or the project's .claude/skills/ folder.
- 4Or upload it in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the skill.
- 5Ask for a report. Describe the report you want in plain language, such as audit events or per-user usage.
- 6Review the agent's commands. Check that the agent inspected the help and schema output and that the parameters match your request before results are used.
What the gws-admin-reports skill lets the agent do
An agent skill is a folder with a SKILL.md file that tells an AI agent how to perform a certain kind of task. This one is about Google Workspace admin reporting, which is built on the Google Workspace Admin SDK.
Once installed, the agent can look up activity logs for a customer's account and a given application, such as the Admin console or Google Drive. It can also fetch customer usage reports, entity usage reports and user usage reports. It can set up push notifications for new account activity and stop those notification channels.
- activities list: retrieve activity logs for an application such as the Admin console or Google Drive
- activities watch: start receiving push notifications for account activity
- channels stop: stop watching resources through a channel
- customerUsageReports get: a usage report for the whole customer account
- entityUsageReports get: usage statistics for entities used by users in the account
- userUsageReport get: usage statistics for a set of users
Install the skill (ZIP download or Claude apps)
Download the skill ZIP from this page and unzip it. For a personal setup, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.
You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload it there.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills
Set up the gws tool and authentication
The skill depends on the gws command-line tool (Google Workspace CLI), which must be installed first. The skill also needs Google Workspace authentication configured through the gws shared skill, which lives at ../gws-shared/SKILL.md. The skill's own file says that shared file covers auth, global flags and security rules.
If the shared skill file is missing, the skill file says to run gws generate-skills to create it. You need administrator access to the Google Workspace tenant, because the reports require it.
- gws command-line tool installed
- Authentication configured via the gws shared skill (../gws-shared/SKILL.md)
- Administrator access to the Google Workspace tenant
gws generate-skillsAsk for reports in natural language
You do not need to remember the command syntax. Describe what you want in plain words, mentioning the kind of data (audit logs, customer usage, entity usage, user usage) and the time period or application if it matters. The skill tells the agent to check the gws help and schema output before running any command, so the agent can pick the right parameters.
Under the hood, commands follow one pattern: a resource, a method and optional flags. Before calling a method, the agent inspects it with the help command and the schema command.
- Good: 'Show me Admin console audit events from the last week.'
- Good: 'Summarise per-user usage of Google Drive for last month.'
- Good: 'Set up push notifications for new account activity.'
- Less useful: 'Fix my Workspace settings.' The skill reads reports and manages notification channels; it does not change settings.
gws admin-reports <resource> <method> [flags]
gws admin-reports --help
gws schema admin-reports.<resource>.<method>Check parameters before running a command
The skill directs the agent to inspect each method before calling it. The help output lists the resources and methods, and the schema output shows a method's required parameters, types and defaults. The agent uses that output to build its --params and --json flags.
If you are a developer running commands yourself, you can use the same two commands to explore the options before you write a script.
- Browse resources and methods with the help command
- Inspect required parameters, types and defaults with the schema command
- Build --params and --json flags from the schema output
gws admin-reports --help
gws schema admin-reports.activities.listSafety notes: scripts, network and sensitive data
This skill runs scripts and uses the network. The commands it runs call Google Workspace APIs using your administrator credentials, so the results come from your live tenant.
Audit and usage data can reveal sensitive information about user activity. Running the skill against live tenant data may expose that activity to the agent's session. Only use it on accounts and data you are authorised to review, and review what the agent does with the output.
- The skill runs scripts and makes network calls
- Results come from live tenant data when authenticated
- Activity data may be sensitive; limit who sees the agent session
- The skill cannot grant admin rights and does not change settings
What people use it for
- Summarising Admin console and Google Drive audit events for a review period
- Reporting customer-wide usage trends for an IT or data team
- Comparing per-user or per-entity usage of Workspace tools to see adoption
- Setting up push notifications so new account activity is delivered as it happens
- Developers automating admin reporting through the gws CLI
Frequently asked questions
How do I install the gws-admin-reports skill?
Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings, then Capabilities, then Skills.
What do I need before the skill works?
You need the gws command-line tool installed, Google Workspace authentication configured through the gws shared skill at ../gws-shared/SKILL.md, and administrator access to the Google Workspace tenant. The reports require admin access, and the skill cannot grant it.
Can a regular Google Workspace user use this skill?
No. The reports require administrator access. Users without admin rights cannot use the skill to read these reports, and the skill cannot give them that access.
Will the agent change my Google Workspace settings?
No. According to the skill's description, it covers reading reports and managing notification channels. It is not meant to change settings or act on what it finds.
What should I do if the skill says the shared file is missing?
The skill file says to run gws generate-skills to create the shared skill. Then make sure the gws tool and authentication are set up as described in the shared skill file.
Is this skill free and open source?
The skill is licensed under Apache-2.0. The gws tool and its Google Workspace access still need to be installed and set up separately, so check the requirements above.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a Google Workspace administrator, or an IT, data or developer team, who wants an agent to read audit logs and usage reports through the gws CLI. Pick something else if you lack admin rights, if you want an agent that changes settings, or if you are not comfortable exposing live user activity data to an agent session.
Download the skill