organise-agent-skills
Skill28 starsChanged 2 days agoMITView on GitHub
Standardised workflow for auditing, cleaning, de-duplicating, pruning, and organising agent skills in Antigravity and Gemini environments. Performs filesystem auto-discovery, orphan pruning, and `skills.json` synchronisation to keep prompt context overhead lean (~30–50 active skills). Use when auditing, cleaning, or de-duplicating installed skills, auto-syncing `skills.json` against disk, pruning token bloat, disabling sub-skills managed by meta-skills, or writing on-demand activation rules in `config/rules/on-demand-skills.md`, `GEMINI.md`, or `AGENTS.md`.
In this repository10 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 3 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
When an agent turn starts, the name and description of every Installed and inactive (discoverable) skill are injected into the system …
- Very specific: line 62
Read skills.json (~/.gemini/config/skills.json) and compare all standalone config/skills/ directories against entries in the exclude array.
- Distinctive: line 72
Check if total discoverable skills exceed the 30–50 skill sweet spot (~3,000–3,500 tokens), which triggers automatic skill dropping by …
- Very specific: line 93
Ensure deleted skills are pruned from ~/.agents/.skill-lock.json so npx skills update -g -y does not re-download them.
- Very specific: line 94
Ensure .gitignore contains regex patterns ([-_]) ignoring standalone versions of plugin skills.
- Very specific: line 110
Keep the master meta-skill enabled in skills.json (e.g.
- Very specific: line 125
Run uv run scripts/reconcile_skills.py --write (or ./scripts/sync_skills.sh), which automatically appends any newly excluded standalone …
- Very specific: line 141
When executing organise-agent-skills (or via ./scripts/sync_skills.sh and uv run scripts/reconcile_skills.py --write):
- Very specific: line 142
Auto-Register Missing Standalone Skills: Add any standalone skill folder found in config/skills/ that is absent from skills.json …
- Very specific: line 143
Prune Orphaned & Plugin Entries: Remove entries from skills.json whose standalone directory in config/skills/ no longer exists, as well as …
- Distinctive: line 179
Ask the user for explicit confirmation before proceeding with any file deletions or configuration changes.
- Distinctive: line 190
Always update the project README.md to document the active skill profile and meta-skill hierarchy.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Organising Agent Skills
[!IMPORTANT] Mandatory User Confirmation Guardrail: The agent MUST NOT delete any skill directories, disable/enable skills in configuration files (
skills.json), or mutate configuration/rules documents (config/rules/*.md,GEMINI.md,AGENTS.md,README.md) without first presenting the audit findings, proposed actions, and token metrics to the user and receiving explicit confirmation to proceed.
This skill provides a repeatable workflow for auditing, cleaning, de-duplicating, and organising agent skills in Antigravity and Gemini environments. It keeps your startup prompt context lean (~30–50 active skills / ~3,000 tokens per turn) and synchronises skills.json against disk without losing access to any skill in your library.
Table of Contents
- Overview & Token Budgeting
- Skill Lifecycle & States
- Workflow Phase 1: Audit & Discovery
- Workflow Phase 2: Meta-Skill Delegation
- Workflow Phase 3: On-Demand Rules (
config/rules/on-demand-skills.md/AGENTS.md) - Workflow Phase 4: Portability &
skills.jsonStandalone Inventory - Workflow Phase 5: User Response & Documentation Update
Overview & Token Budgeting
When an agent turn starts, the name and description of every Installed and inactive (discoverable) skill are injected into the system prompt context.
- The Problem: Over-accumulating skills (100+ discoverable skills) injects 6,000–10,000+ tokens into every single interaction turn, wasting context budget and causing LLM decision fatigue (hallucinating or picking the wrong skill due to description overlap).
- The Target State: Maintain a lean core of ~30 to 50 discoverable skills (~3,000 tokens prompt overhead), placing specialised or sub-skills into an Installed and excluded state, using meta-skill routing and modular
model_decisionrules (config/rules/on-demand-skills.md) for everything else.
Skill Lifecycle & States
Skills operate in three states within agentic development environments such as Antigravity:
| State | skills.json Entry | Startup Token Cost | How It Activates |
| 1. Discoverable (Installed & inactive) | "//skill-name" (comment-prefixed or unlisted) | Level 1 frontmatter (name + description) loaded every turn | Agent matches the pre-loaded description automatically |
| 2. Excluded (Installed on disk) | "skill-name" (plain string in exclude) | 0 tokens until needed | Activated on demand via meta-skills or config/rules/on-demand-skills.md |
| 3. Activated (Loaded in current turn) | N/A (runtime state) | Level 2 (SKILL.md body) + optional Level 3 files | Agent reads the skill's SKILL.md for the active task |
Workflow Phase 1: Audit & Discovery
- Filesystem Auto-Discovery & Full Inventory Audit:
- Standalone Skills: List all skill directories present on disk under
~/.gemini/config/skills/(and.agents/skills/if in a workspace). - Packaged Plugin Skills: Inspect all bundled skills inside
~/.gemini/config/plugins/*/skills/and parked skills in~/.gemini/config/plugins/*/skills.all/. Note thatskills.jsonstrictly filters standalone skills inconfig/skills/— never add plugin skill names toskills.json(they are no-ops). Antigravity loads all skills inside an enabled plugin'sskills/directory as a bundle. Large plugins (such asdata-agent-kit-plugin, 40 skills) should be disabled ("enabled": falseinconfig/config.json), and specialised plugin sub-skills (e.g. insidechrome-devtools-pluginorgoogle-cloud-developer) can be parked intoskills.all/viascripts/sync_skills.shso they remain readable on demand at zero startup token cost. - Marketplace Auto-Updates on Disabled Plugins: Antigravity updates installed Marketplace plugins on disk even when
"enabled": falseinconfig/config.json. When a plugin auto-updates, the upstream archive replaces the plugin directory withoutskills.all/and may bundle new skills that collide with standalone skills inconfig/skills/. Always run./scripts/sync_skills.sh(which invokesscripts/reconcile_skills.py --write) to restoreskills.all/, re-park sub-skills, remove newly duplicated standalone skills, and prune retired skill entries. - Read
skills.json(~/.gemini/config/skills.json) and compare all standaloneconfig/skills/directories against entries in theexcludearray. - Identify Discrepancies:
- Newly Discovered Standalone Skills: Standalone skill folders present in
config/skills/but missing fromskills.json. - Active Plugin Skills: Plugin skills inside enabled
config/plugins/*/skills/(counted towards the active Level 1 prompt budget, managed via plugin enablement orskills.all/parking rather thanskills.json). - Orphaned or No-Op Plugin Entries: Entries in
skills.json(with or without//) whose standalone directory no longer exists inconfig/skills/(including plugin skill names that do not belong inskills.json). - Installed and Excluded Skills: Standalone skills listed in
skills.jsonwithout the//string prefix. - Installed and Inactive (Discoverable) Skills: Standalone skills listed in
skills.jsonwith the//string prefix.
- Newly Discovered Standalone Skills: Standalone skill folders present in
- Standalone Skills: List all skill directories present on disk under
- Measure Prompt Footprint:
- Sum word/token count of descriptions across all active discoverable skills (including unlisted plugin skills).
- Check if total discoverable skills exceed the 30–50 skill sweet spot (~3,000–3,500 tokens), which triggers automatic skill dropping by Antigravity's context budget manager.
Mandatory Semantic & Functional Overlap Audit: The agent MUST systematically inspect the skill inventory for duplicate, legacy, or redundant skills. Do NOT rely solely on literal folder names or string distance matching.
- Semantic & Methodological Analysis:
Parse the YAML frontmatter (
description), primary headings, and operational directives of each skill. Look for shared software engineering methodologies or overlapping tools disguised by differing folder names. Example: An extension plugin namedconductorduplicates a standalone skill namedspec-driven-developmentbecause both implement Spec-Driven Development (SDD) workflows. - Functional Domain Clustering:
Group skills into semantic domain clusters and flag clusters where multiple active skills compete or create routing collisions:
- Gemini API & SDK: e.g.
gemini-apivsgemini-api-dev/gemini-interactions-api. - Spec-Driven Development & Planning: e.g.
spec-driven-developmentvsconductor/planning-and-task-breakdown. - Browser DevTools & Automation: e.g.
chrome-devtoolsvsbrowser-testing-with-devtools/playwright-cli. - Cloud Authentication: e.g.
gcloud-auth-verificationvsgoogle-cloud-auth-verification. - Workflow Orchestration: e.g.
gcp-composer-troubleshootingvsmanaged-airflow-dag-troubleshooting. - Data Platforms & Storage: e.g. BigQuery, Spark, Dataproc, GCS.
- Gemini API & SDK: e.g.
- Packaged Plugin Supersession:
Cross-reference standalone skills against official packaged extension plugins (
config/plugins/). When an upstream plugin bundles skills covering a domain, the standalone copies are obsolete:- Flag obsolete standalone skills for deletion from disk.
- Ensure deleted skills are pruned from
~/.agents/.skill-lock.jsonsonpx skills update -g -ydoes not re-download them. - Ensure
.gitignorecontains regex patterns ([-_]) ignoring standalone versions of plugin skills.
- Action: Explicitly propose deleting redundant skill directories and disabling overlapping variants in the Pre-Execution Proposal.
- Semantic & Methodological Analysis:
Parse the YAML frontmatter (
Workflow Phase 2: Meta-Skill Delegation
Identify master meta-skills that orchestrate sub-skills:
- Master Routers:
- E.g. the skill
using-agent-skillsorchestrates the 23 senior engineering SDLC sub-skills. - E.g. the skill
google-agents-cli-workfloworchestrates ADK agent development sub-skills (scaffold,code,deploy,eval,observability). - E.g. the skill
gcp-data-pipelinesorchestrates Dataflow, Dataform, dbt, Dataproc, and BigQuery data pipeline tools.
- E.g. the skill
- Action:
- Keep the master meta-skill enabled in
skills.json(e.g."//using-agent-skills"). - Disable child sub-skills in
skills.json(plain string without//). - The master meta-skill will instruct the agent to inspect and read sub-skill files from disk on demand.
- Keep the master meta-skill enabled in
Workflow Phase 3: On-Demand Rules (config/rules/on-demand-skills.md / AGENTS.md)
Whenever disabling a specialised or niche domain skill in skills.json (skills that are not sub-skills of an active master meta-skill), ensure an on-demand routing entry exists in a modular model_decision rule (config/rules/on-demand-skills.md globally, or workspace .agents/rules/ / AGENTS.md) rather than bloating always-on GEMINI.md:
- Disable in
skills.json:- Exclude the standalone domain skill from automatic Level 1 prompt injection (plain string in
exclude).
- Exclude the standalone domain skill from automatic Level 1 prompt injection (plain string in
- Curated Domain Table + Automated Self-Maintenance:
- Group related excluded skills into a concise domain routing table inside
config/rules/on-demand-skills.md(trigger: model_decisionwith a broad domain-agnostic trigger description so newly installed skills in new domains remain activatable without editing the trigger). - Run
uv run scripts/reconcile_skills.py --write(or./scripts/sync_skills.sh), which automatically appends any newly excluded standalone skills not yet referenced inconfig/rules/on-demand-skills.mdbetween<!-- AUTO-GENERATED-EXCLUDED-SKILLS:START -->and<!-- AUTO-GENERATED-EXCLUDED-SKILLS:END -->using each skill's frontmatter summary.
- Group related excluded skills into a concise domain routing table inside
Workflow Phase 4: Portability & skills.json Standalone Inventory
To ensure maximum visibility and effortless toggling without no-op clutter, skills.json is treated as an explicit full inventory control panel for standalone skills in config/skills/ (never plugin-bundled skills).
Antigravity skills.json Mechanics
- Location:
~/.gemini/config/skills.json(or workspace.agents/skills.json). - Installed and excluded: Plain string in
excludearray (e.g."alloydb-basics"). Exact match evaluates totrue, excluding the standalone skill from Level 1 prompt loading. - Installed and inactive (discoverable):
//prefix inexcludearray (e.g."//bigquery-basics"). The//prefix breaks exact string match (exclude.includes("bigquery-basics")evaluates tofalse), causing the loader to treat the standalone skill as discoverable (frontmatter automatically read into Level 1 prompt context).
Reconciliation & Auto-Sync Procedure
When executing organise-agent-skills (or via ./scripts/sync_skills.sh and uv run scripts/reconcile_skills.py --write):
- Auto-Register Missing Standalone Skills: Add any standalone skill folder found in
config/skills/that is absent fromskills.json(defaulting to excluded unless explicitly enabled with//). - Prune Orphaned & Plugin Entries: Remove entries from
skills.jsonwhose standalone directory inconfig/skills/no longer exists, as well as any no-op plugin skill names. - Sync On-Demand Rule: Populate any unmapped excluded standalone skills into
config/rules/on-demand-skills.md. - Sort Alphabetically: Maintain the
excludearray sorted alphabetically (ignoring leading//) so scanning and diffing remain clean and predictable.
Example skills.json:
{
"exclude": [
"accidental-data-loss-prevention", // INSTALLED AND EXCLUDED (no // prefix)
"//agent-aware-cli", // INSTALLED AND INACTIVE / DISCOVERABLE (// prefix workaround)
"//using-agent-skills", // INSTALLED AND INACTIVE / DISCOVERABLE (Master Meta-Skill)
"spec-driven-development" // INSTALLED AND EXCLUDED (Sub-skill activated on-demand)
]
}Portability Notes
skills.jsonis the native exclusion mechanism for Antigravity environments.- For other agent frameworks (e.g. Claude Code, Cursor, Windsurf), skill exclusion is managed via workspace
.agents/boundaries or tool configuration files. Disabling via meta-skills and on-demand file reading remains 100% portable across all LLM agents.
Workflow Phase 5: User Response & Documentation Update
Pre-Execution Proposal: Present the audit findings, redundant skill breakdown, and proposed actions to the user with a summary proposal table:
Metric Baseline (Unoptimised) Proposed (Optimised) Delta Installed Skill Directories N M -X Installed & Discoverable Skills N M -X Installed & Excluded Skills N M +X Prompt Token Overhead ~A tokens ~B tokens -C tokens Ask the user for explicit confirmation before proceeding with any file deletions or configuration changes.
- Post-Execution Summary Table:
Once approved and executed, present the final metrics table showing exact deltas alongside a clear breakdown of what was done:
- Installed & Discoverable Skills: Skills whose frontmatter is pre-loaded into Level 1 prompt context.
- Installed & Excluded Sub-Skills: Skills read and activated on demand by parent meta-skills.
- Installed & Excluded On-Demand Skills: Skills activated via
config/rules/on-demand-skills.md,GEMINI.md, orAGENTS.mdrules. - Installed & Excluded Domain Skills: Niche/specialised skills kept excluded until explicitly activated.
- Deleted / Retired Skills: Obsolete or duplicate skills removed from disk.
- Documentation Update:
Always update the project
README.mdto document the active skill profile and meta-skill hierarchy.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

