Shared Skills — Repo Digest

This is the reference digest. It is the first real repository processed for the portal and sets the documentation standard every future repo digest must follow (see the section order and depth here, mirrored in templates/repo-digest.template.md).

What it is

A curated library of 169 Agent Skills — modular, self-contained capability packages that extend Claude (and other AI coding tools) with domain expertise, procedures, templates, and executable scripts. Each skill is a directory containing a SKILL.md (instructions + metadata) plus optional references/, scripts/, assets/, and templates/. It is the foundational capability layer of Azwaan’s AI venture ecosystem.

Why it exists

Every venture, platform, product, and agent in the ecosystem needs the same underlying competencies — architecture, documentation, diagramming, cloud engineering, security, marketing, sales, product, finance, and operations. Rather than re-teaching those competencies to each project, they are factored once into reusable skills and shared across the whole ecosystem. This repo is where capability is manufactured and standardized; downstream layers consume it. It exists so that the ecosystem’s intelligence compounds: improving a skill upgrades every venture that uses it.

At a glance

Assumption / uncertainty (recorded): At review time ~/.claude/skills is a local directory, not an initialized git repository, and has no repo-level README/CLAUDE.md. Skill content files are largely OneDrive cloud placeholders, so POSIX find/glob under-report; counts above were verified with Windows-API tooling (PowerShell). If this library is later promoted to a first-class git repo with its own root docs, revisit this digest.

Business capability provided

Reusable AI competence as infrastructure. The repo supplies ready-made, standardized expertise that any part of the ecosystem can invoke on demand — turning “we need someone who knows X” into “we have a skill for X.” It is the ecosystem’s skills marketplace and standard library rolled into one.

Technical responsibilities

• Package domain expertise into self-contained, discoverable Agent Skills using the SKILL.md format.
• Provide progressive disclosure: a lightweight SKILL.md entry point that pulls in heavier references/, scripts/, and assets/ only when needed.
• Ship deterministic tooling (Python/TS/shell scripts) for skills that require computation rather than prose (e.g. diagram generation, dependency analysis, process/cycle-time math).
• Maintain metadata contracts (name, description-as-trigger, version, license, tags, compatible_tools, context) that make skills routable by the harness.
• Not responsible for: runtime orchestration of agents, hosting products, or storing customer data — those belong to higher layers.

Core concepts

Key workflows

1. Invocation — the harness surfaces skills; a user’s request matching a skill’s description triggers it; the agent reads SKILL.md and, as needed, its references//scripts/.
2. Authoring — a new capability is captured as SKILL.md + supporting files, versioned, licensed, and tagged, following the established skill format.
3. Composition — skills reference sibling skills (“For X, see Y-skill”), forming an informal capability graph across domains.
4. Execution — computational skills shell out to their bundled scripts for deterministic output.
5. Curation / upkeep — skills are added, versioned, and pruned (a .last-cleanup marker and backups/ were observed under ~/.claude).

Technologies used

• Primary medium: Markdown (SKILL.md, references/*.md) — 370 .md files observed.
• Scripting: Python (referenced throughout skill bodies, e.g. senior-architect, knowledge-ops, process-mapper, dependency-auditor), TypeScript (10 files), Shell (6 files); plus JSON, TOML, HTML.
• Format standard: Anthropic Agent Skills (SKILL.md front-matter + progressive disclosure).
• Distribution/compat: cross-tool via compatible_tools; open-source licensed (MIT, Apache-2.0).

Major modules / components

The library is best understood as domain clusters (≈169 skills). This clustering is the raw material for the ecosystem’s higher layers and for duplication analysis.

Full per-skill descriptions live in each skill’s SKILL.md. A complete inventory is intentionally not duplicated here — see the Shared Skills system digest.

Capabilities

• skill-authoring — a standard format & method for packaging AI capabilities
• architecture-tooling — Mermaid/PlantUML diagram + dependency generation (senior-architect)
• documentation-generation — Diátaxis docs, READMEs, specs, ADRs, llms.txt
• diagram-generation — draw.io, Excalidraw, Mermaid, BPMN process maps
• dependency-analysis — multi-language dependency & license auditing
• knowledge-ops — SOP/runbook hygiene, orphan/dead-link detection
• go-to-market — end-to-end marketing/sales/growth competence
• cloud-architecture — AWS/Azure/GCP/Cloudflare design
• agent-engineering — multi-agent design, RAG, prompt optimization

These capabilities are the inputs the future portfolio-portal-orchestrator will itself consume.

Upstream dependencies

Downstream consumers

This is a foundational layer — nearly everything can consume it. Concretely:

Only the portal is a realized consumer today; the rest are planned layers (see portfolio overview). Recorded as forward-looking, not asserted as built.

Major interfaces & integration points

• Consumes: the AI harness (skill routing), external APIs invoked by individual skills.
• Exposes:
  • SKILL.md trigger descriptions — the interface the harness matches intent against.
  • Reference documents (references/*.md) — deep knowledge loaded on demand.
  • Executable scripts (scripts/) — deterministic tools with documented CLIs.
  • Templates & assets (templates/, assets/) — copy-ready artifacts.
  • Metadata (name, version, tags, compatible_tools) — machine-routable contracts.

Reusable assets exposed to other repositories

• 169 invocable skills across 10 domain clusters.
• Deterministic scripts — e.g. senior-architect/scripts/architecture_diagram_generator.py, dependency_analyzer.py, project_architect.py; knowledge-ops/process-mapper analysis tools.
• Document templates — README, spec, ADR, llms.txt scaffolds.
• Design tokens & brand onboarding — design-system, ui-design-system.
• A reusable authoring standard — the SKILL.md format itself, which the orchestrator skill will target.

Architectural decisions

• Skills are self-contained and progressively disclosed (keep SKILL.md light).
• Skills are triggered by description, not called by name (routing is intent-based).
• Determinism via scripts where prose would be unreliable.
• Cross-tool portability via compatible_tools and open-source licensing.
• Portal-level decision to treat Shared Skills as the foundation layer: see ADR 0002.

Architecture snapshot

graph TD
    subgraph Skill["Anatomy of a Skill"]
        SM[SKILL.md<br/>front-matter + instructions] --> REF[references/*.md]
        SM --> SCR[scripts/ py·ts·sh]
        SM --> AST[assets/ · templates/]
    end
    Harness[AI Harness / Agent SDK] -->|matches description| SM
    SM -->|invokes| SCR
    SM -.->|composes with| SM2[Other skills]

    subgraph Library["Shared Skills Library — 169 skills, 10 clusters"]
        Eng[Engineering & Arch]
        Cloud[Cloud & Infra]
        Sec[Security]
        AI[AI / Agents / Data]
        Docs[Docs / Diagrams]
        Prod[Product / PM]
        Design[Design / Frontend]
        Mktg[Marketing / GTM]
        Sales[Sales / RevOps / Fin]
        Ops[Ops / Bizops]
    end

Current maturity

Operational. Rationale: 169 skills are present and actively used (this portal was built with them); the library is versioned (68 skills carry a version), licensed, multi-author, and under active curation (observed backups/ and a .last-cleanup marker). It is not “production” in a hosted-SLA sense — it is a local, curated developer asset without CI, tests, or a published release process. Hence operational, not production.

Roadmap

Near-term themes (see roadmap):

• Promote the library to a first-class git repo with root README/CLAUDE.md and CI hygiene checks.
• Build portfolio-portal-orchestrator (Phase D) that consumes these skills to automate the portal.
• Add an internal skills index / taxonomy and de-duplicate overlapping capabilities (see review notes).

Known limitations

• No repo-level docs or git history at review time — no root README/CLAUDE.md, not a git repo.
• No automated tests or CI for skills; quality is by curation.
• Capability overlap — several clusters contain near-duplicate skills (e.g. revops vs revenue-operations; database-designer vs database-schema-designer; multiple senior-*).
• Discoverability relies on description quality; there is no unified taxonomy/index inside the repo.
• Cloud-placeholder storage makes some tooling (POSIX find, glob) under-report contents.

Future opportunities

• A skills registry/taxonomy file inside the repo (the orchestrator could generate it).
• Consolidation of duplicated skills to reduce routing ambiguity.
• Test/eval harness to regression-check skill outputs.
• Packaging as a shareable/publishable skills pack (it already carries open-source licenses).
• Treat the library as a product (a curated AI skills distribution) — a commercialization path.

Relationship to the wider AI venture ecosystem

Shared Skills is the bottom, load-bearing layer of the layered architecture described in the Portfolio Overview. Intelligence flows upward: skills manufacture capability → the Intelligence Platform turns capability into processed intelligence → Intelligence Products package it → Applications & Agents operationalize it → Customer-facing Solutions deliver it. Because improving one skill upgrades every dependent layer, this repo is the ecosystem’s primary point of compounding leverage. See system-of-systems architecture.

Links

• Source: ~/.claude/skills (local, private)
• System digest: shared-skills
• Registry row: repo registry
• Architecture review notes: recommendations
• Portfolio overview: portfolio-overview