CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Shared Skills is a modular AI agent library for business advisory, built on the Agent Skills standard. It provides specialized agent personas (CFO, tax advisor, legal, marketing, etc.) as Claude Code skills, distributed via plugin marketplace or git submodules.

Architecture

Skills (skills/)

Each skill is a directory with a SKILL.md file using YAML frontmatter for routing metadata and markdown body for instructions. The frontmatter description field controls when the skill triggers — it should be "pushy" (undertriggering > overtriggering). Skills reference supporting files via references/ subdirectories. Auto-discovered by the plugin system.

Plugin System (.claude-plugin/)

• plugin.json — plugin manifest (name, description, author, license)
• Skills are auto-discovered from skills/ directory — no explicit paths needed

Hooks (hooks/)

Plugin-shipped hooks (hooks/hooks.json plus Node scripts) that back the session working mode: session-start.mjs injects the rule set, user-prompt-submit.mjs reinforces it each turn, session-end.mjs clears the session's state. mode.mjs is the switch behind /ss:working-mode; rule text lives in hooks/rules/*.md so the trigger and stop lists can be tuned on their own. State is keyed by session id under ~/.claude/ss/agent-working-mode/.

Nothing is ever written into ~/.claude/settings.json or ~/.claude/hooks/. Everything ships inside the plugin, so disabling the plugin genuinely stops it. Hooks must fail silently, emit nothing when the mode is off, and never block a prompt. node hooks/selftest.mjs verifies the on path, the off path, session isolation, and the silent-failure paths against a sandboxed state directory.

Tools (tools/)

Lightweight CLI scripts (bash/python) for external API integrations (ClickUp, Revolut). Preferred over MCP servers to minimize context window usage. Shared helpers in tools/common/helpers.sh. Setup: cp tools/common/.env.example tools/common/.env.

Templates (templates/)

• SKILL_TEMPLATE.md — skeleton for new agent skills
• CONTEXT_TEMPLATE.md — skeleton for organization-specific context files
• CLAUDE_MD_TEMPLATE.md — skeleton for multi-agent system CLAUDE.md

OpenSpec (openspec/)

Project specification used with the OpenSpec workflow skills (opsx:*) for structured change management.

Context Layer (company/ and context/)

User-specific data lives outside the skills — company data in company/, the other context files in context/ — separate from domain knowledge in skill references/. This enables clean distribution: fork/install → run environment-setup skill → ready to use. Company data used to live in context/ and moved to company/; the skills read only the new paths, with no fallback to the old ones (see CHANGELOG.md).

Architecture:

• context/templates/ — tracked in git, distributed with repo. Template files with [DO UZUPELNIENIA] placeholders, for every context file including the company data (only the place a finished file is saved differs)
• company/data/*.md — company data (company.md, legal-entities.md). Created by users (manually or via environment-setup skill). Gitignored in this repository (the fork flow); when the plugin is used inside your own repository, you decide whether company/ is tracked there
• company/brand/ — optional brand files (writing-style.md, brand-design.md, tone-of-voice.md) with no templates, gitignored in this repository. Read by linkedin-content and /ss:slides:init when they exist
• context/*.md — gitignored. Created by users (manually or via environment-setup skill)
• references/ — domain knowledge only (methodologies, frameworks, checklists). Stays in each skill

Context types:

Skill convention: Each skill that uses context files MUST have a ## Context Dependencies section listing required/recommended files and a warning message for missing files.

Key Conventions

• Skills use progressive disclosure: metadata → body → references (load references only when needed)
• All skills are Apache 2.0 licensed
• Language: many agent skills target Polish-speaking users (tax, legal, business consulting contexts)

Setup Workflow (for users)

1. Fork or plugin install — git clone/git submodule add or /plugin marketplace add 200iqlabs/shared-skills
2. Run environment-setup skill — guides through creating context files step-by-step
3. Ready to use — skills automatically load domain knowledge + user context

Creating or Modifying Skills — MANDATORY workflow

When creating a new skill or significantly modifying an existing one, you MUST use the /skill-creator workflow. Do NOT write SKILL.md files directly.

Required steps:

1. /skill-creator — capture intent, interview for edge cases, draft SKILL.md
2. Generate test prompts (min. 5 per agent)
3. Run evals and review results
4. Iterate based on feedback and benchmarks
5. Optimize description for triggering accuracy (target ≥ 80%)

Why: Hand-written skill descriptions undertrigger. skill-creator's interview process surfaces edge cases, and its eval loop ensures the description actually works. Skipping this produces lower-quality agents.

When to use skill-creator:

• Building a new skill from scratch
• Replacing a placeholder skill with a real implementation
• Rewriting or significantly expanding a skill's description or instructions
• Optimizing triggering accuracy for an existing skill

When you can skip it:

• Minor edits (typo fixes, adding a reference file, updating a date)
• Changes only to reference files or scripts (not SKILL.md itself)