# Agent Skills Architecture

> Foundational "High-Density" standard for token-optimized agent instructions and CLI-based automated activation.

- Skill: `fierzone/agent-skills-architecture` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fierzone/agent-skills-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fierzone/agent-skills-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: fierzone (https://skillmd.com/u/fierzone)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fierzone/agent-skills-architecture

---


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