home / skills / hoangnguyen0403 / agent-skills-standard / agent-skills-architecture

agent-skills-architecture skill

Q: How does the CLI decide which skills to exclude?

CLI reads project manifests, maps dependencies to skill IDs, and adds missing-package sub-skills to exclude list during initialization.

Q: What belongs in the core skill body vs references?

Core body: imperative, compact instructions and checks (<500 lines). References: large examples, migration scripts, long code samples loaded lazily.

/.agent/skills/common/agent-skills-architecture

This skill helps you organize and apply high-density agent instructions with language-specific package separation and CLI-driven activation.

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill agent-skills-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: Agent Skills Architecture
description: Foundational "High-Density" standard for token-optimized agent instructions and CLI-based automated activation.
metadata:
  labels: [architecture, high-density, meta, optimization, cli-integration]
  triggers:
    files: ['.skillsrc', 'metadata.json', 'SKILL.md']
    keywords:
      [
        skill architecture,
        high-density standard,
        modular skills,
        dependency exclusion,
        skill separation,
      ]
---

# Agent Skills Architecture Standard

## **Priority: P0 (CRITICAL)**

The primary goal is **Maximum Information Density** and **Automated Precision**.

## 🏗️ Core Architectural Pillars

### 1. **Separation by Package (Granularity)**

- **Rule**: Separate skills based on specific library/framework dependencies.
- **Goal**: Avoid context pollution. Don't load "Riverpod" instructions into a "BLoC" project.
- **Example**: `flutter/bloc-state-management` vs `flutter/riverpod-state-management`.

### 2. **Presence = Active (Simplified Configuration)**

- **Logic**: If a skill is listed in `.skillsrc`, it is considered active.
- **Standard**: Remove legacy `enabled` flags. Control activation via inclusion/exclusion lists.

### 3. **CLI Detection & Dynamic Exclusion**

- **Mechanism**: The CLI (`ags`) maps `package.json`/`pubspec.yaml` dependencies to skill IDs.
- **Exclusion**: Irrelevant sub-skills are automatically added to the `exclude` list during initialization if their corresponding packages are missing.

### 4. **Progressive Disclosure (Three-Level Loading)**

- **Level 1 (Metadata)**: Triggers activation via high-precision keywords/files.
- **Level 2 (SKILL.md Body)**: Core imperative logic (<500 lines). No conversational fluff.
- **Level 3 (References)**: Detailed examples, complex patterns, scripts. Lazy-loaded on-demand.

## 📦 ID & Naming Standards

- **Category**: Lowercase letters (e.g., `flutter`, `nestjs`).
- **Skill ID**: Kebab-case, must match the directory name.
- **Registry ID**: Must match the Skill ID for automated CLI detection/exclusion.

## 📋 High-Density Writing Style

- **Imperative Mood**: Use "Use X", "Avoid Y". No "Please" or "You should".
- **Token Compression**: Skip articles ("the", "a") where possible. Use bullet points > paragraphs.
- **Anti-Patterns**: Avoid conversational intros ("In this skill, we see...").

## 🔗 Internal References

- [Skill Creator Standard](../../skill-creator/SKILL.md) - Detailed authoring rules.
- [Resource Organization](../../skill-creator/references/resource-organization.md) - Folder structure best practices.

Overview

This skill defines a high-density standard for token-optimized agent instructions and CLI-driven activation. It organizes skills by package granularity, enforces presence-as-active configuration, and implements progressive disclosure to minimize context load. The standard focuses on automated detection and exclusion via dependency mapping to keep agents precise and lightweight.

How this skill works

Inspect project manifest files (package.json, pubspec.yaml, go.mod, composer.json) to map dependencies to skill IDs. Activate skills by presence in a central skills list; automatically exclude sub-skills whose packages are missing. Load content in three progressive levels: metadata for detection, compact imperative logic for runtime, and detailed references lazily on demand.

When to use it

Setting up agent instruction sets for multi-framework repos
Automating skill activation via CLI in CI/CD or local dev environments
Reducing token usage for large language agents by limiting context
Maintaining clear separation between framework-specific guidance
Onboarding new skills into an existing agent ecosystem

Best practices

Split skills by specific library/framework; avoid mixed-framework instructions
Manage activation via inclusion lists; remove legacy enabled flags
Map manifest dependencies to skill IDs for dynamic exclusion
Write core skill body in concise imperative style (<500 lines)
Expose heavy examples and scripts only in lazily loaded references
Name skill directories and IDs in kebab-case to ensure deterministic detection

Example use cases

Auto-detect Flutter vs React Native and load only relevant state-management skills
CI job that initializes .skillsrc based on repository dependencies
Agent serving code that keeps runtime tokens low by loading only metadata and compact logic
Tooling that scans mono-repo and excludes irrelevant platform skills automatically
Authoring a TypeScript skill for NestJS that follows the three-level loading pattern

FAQ

How does the CLI decide which skills to exclude?

CLI reads project manifests, maps dependencies to skill IDs, and adds missing-package sub-skills to exclude list during initialization.

What belongs in the core skill body vs references?

Core body: imperative, compact instructions and checks (<500 lines). References: large examples, migration scripts, long code samples loaded lazily.