Organise Agent Skills

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 (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, structured workflow for auditing, pruning, and organising agent skills in Antigravity and Gemini environments. It ensures your prompt context window remains lean (~30–50 active skills / ~3,000 tokens overhead per interaction turn) while retaining full access to all installed skills.

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 (GEMINI.md / AGENTS.md)
• Workflow Phase 4: Portability & skills.json Exclusions
• Workflow Phase 5: 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 GEMINI.md activation rules for everything else.

Skill Lifecycle & States

Skills operate under three explicit states within agentic development environments (such as Antigravity):

1. Installed and inactive (discoverable): These skills are present on disk and discoverable by our agent. When the agent (e.g. Antigravity) starts, their frontmatter (Level 1) is automatically read into context. In skills.json, these entries are prefixed with // or unexcluded.
2. Installed and excluded: These skills reside in your disk library but are excluded from automatic Level 1 loading. For these, the agent does not automatically read their frontmatter and is therefore not directly aware of them during your conversation with it. But because they are present on disk and available to the agent, they can still be explicitly activated. In skills.json, these entries are listed as plain strings without //.
3. Activated: This is the runtime state when a skill's full SKILL.md body is actively loaded into the current turn context. I.e. Level 2 loading, and Level 3, where supporting files are present and appropriate.

Workflow Phase 1: Audit & Discovery

1. Filesystem Auto-Discovery & Inventory Audit:

   • List all skill directories present on disk under ~/.gemini/config/skills/ (and .agents/skills/ if in a workspace).
   • Read skills.json (~/.gemini/config/skills.json) and compare disk directories against entries in the exclude array.
   • Identify Discrepancies:
     • Newly Discovered Skills: Skill folders present on disk but missing from skills.json.
     • Orphaned Entries: Entries in skills.json (with or without //) whose directory no longer exists on disk.
     • Installed and Excluded Skills: Skills listed in skills.json without the // string prefix.
     • Installed and Inactive (Discoverable) Skills: Skills listed in skills.json with the // string prefix.

2. Measure Prompt Footprint:

   • Sum word/token count of descriptions across all active skills.

3. Mandatory Duplicate & Redundancy Audit: The agent MUST systematically inspect the skill inventory for duplicate, legacy, or redundant skills:

   • Byte-for-byte & Description Duplicates: Search for skills with identical or near-identical descriptions/frontmatter (e.g. gemini-agents-api vs gemini-managed-agents-api, gemini-live-api vs liveapi-service).
   • Functional Overlaps: Identify redundant skills where a newer or broader skill supersedes an older one.
   • Action: Explicitly propose deleting redundant skill directories from disk in the Pre-Execution Proposal.

Workflow Phase 2: Meta-Skill Delegation

Identify master meta-skills that orchestrate sub-skills:

1. Master Routers:

   • E.g. the skill using-agent-skills orchestrates the 23 senior engineering SDLC sub-skills.
   • E.g. the skill google-agents-cli-workflow orchestrates ADK agent development sub-skills (scaffold, code, deploy, eval, observability).
   • E.g. the skill gcp-data-pipelines orchestrates Dataflow, Dataform, dbt, Dataproc, and BigQuery data pipeline tools.

2. 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.

Workflow Phase 3: On-Demand Rules (GEMINI.md / AGENTS.md)

Whenever disabling a specialised or niche domain skill in skills.json (skills that are not sub-skills of a master meta-skill), you MUST ensure an activation rule exists in GEMINI.md or AGENTS.md so the agent knows when to enable or inspect it on demand.

1. Disable in skills.json:

   • Exclude the domain skills from automatic prompt injection by default (e.g. plain string in exclude).

2. Mandatory Rule Generation in GEMINI.md or AGENTS.md:

   • Inspect GEMINI.md (or AGENTS.md for workspace skills) under ## Knowledge Rules.
   • If an activation rule for the disabled domain skill does not already exist, you MUST draft and append an activation rule using the following template:

   ### <Domain / Skill Name> Activation Rule
   
   The `<skill-name>` skill is disabled by default in `skills.json` to keep context window overhead lean.
   
   **Activation Rule**: Activate or inspect `<skill-name>` (by adding `//` in `skills.json` or reading on demand) whenever <specific scenario, task type, or trigger conditions>.
   

   Examples:

   • GCS Security Assessment (gcs-security-assessment): Activate whenever auditing bucket access controls, storage security posture, or SAIF compliance.
   • NotebookLM Auth (notebooklm-auth): Activate whenever diagnosing or resolving NotebookLM MCP cookie or authentication errors.

Workflow Phase 4: Portability & skills.json Full-Inventory Management

To ensure maximum visibility and effortless toggling, skills.json is treated as an explicit full inventory control panel for all installed skills rather than a partial list of exclusions.

Antigravity skills.json Mechanics

• Location: ~/.gemini/config/skills.json (or workspace .agents/skills.json).
• Installed and excluded: Plain string in exclude array (e.g. "alloydb-basics"). Exact match evaluates to true, excluding the skill from Level 1 prompt loading.
• Installed and inactive (discoverable): // prefix in exclude array (e.g. "//bigquery-sql"). The // prefix breaks exact string match (exclude.includes("bigquery-sql") evaluates to false), causing the loader to treat the skill as discoverable (frontmatter automatically read into Level 1 prompt context).

Reconciliation & Auto-Sync Procedure

When executing organise-agent-skills:

1. Auto-Register Missing Skills: Add any skill folder found on disk that is absent from skills.json. Default newly registered skills to discoverable ("//skill-name") or excluded ("skill-name") based on user preference or token budget strategy.
2. Prune Orphaned Entries: Remove entries from skills.json whose corresponding directory on disk no longer exists.
3. Sort Alphabetically: Maintain the exclude array sorted in alphabetical order so that 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.json is 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

1. 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.

2. 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 GEMINI.md / AGENTS.md rules.
   • Installed & Excluded Domain Skills: Niche/specialised skills kept excluded until explicitly activated.
   • Deleted / Retired Skills: Obsolete or duplicate skills removed from disk.

3. Documentation Update: Always update the project README.md to document the active skill profile and meta-skill hierarchy.