Candradesm Zsh Config Bootstrapper

When to use me

• When a repo has no .agents/skills/ directory
• When you need to scaffold skills from existing instructions or tech stack

Not intended for

• Updating existing skills → read them first, ask user what to change
• Day-to-day coding → use project-specific skills instead
• Code review → use code-review

Phase 0 — Verify Need (MANDATORY)

Before doing anything, check what already exists:

github_get_file_contents(owner, repo, ".agents/skills/")
github_get_file_contents(owner, repo, ".github/instructions/")

• If .agents/skills/ exists → STOP and ASK user what they want to do. Never overwrite without permission.
• If .github/instructions/ exists → note file paths, they'll be used as source material in Phase 2.

Phase 1 — Discover Repo (GitHub MCP)

Scan the repo to detect tech stack. Use github_get_file_contents and github_list_* — never raw bash.

Step 1: Root Structure

github_get_file_contents(owner, repo, "/")

Step 2: Detect Build System

Step 3: Read Build File

Read the build file to extract:

• Language version
• Key dependencies (frameworks, DI, testing, HTTP)
• Build commands (test, lint, build)
• Linter configuration

Step 4: Detect Source Structure

github_get_file_contents(owner, repo, "src/")

Detect architecture patterns:

• src/main/kotlin/ with domain/, data/, presentation/ → Clean Architecture
• src/main/kotlin/ with commands/, services/ → Command Pattern
• src/ with components/, pages/ → React/frontend
• src/ with controllers/, models/ → MVC
• lib/ → Library project

Step 5: Check for Existing Config

github_get_file_contents(owner, repo, ".github/")

Look for:

• CI/CD workflows (.github/workflows/)
• Issue/PR templates
• CODEOWNERS
• Existing instructions

Phase 2 — Create Skills

Create .agents/skills/ with workflow-level skills derived from tech stack detection and any existing instruction files found in Phase 0.

Relationship: Each skill is a condensed, actionable version of a single topic. If .github/instructions/{topic}.instructions.md exists, use it as source material — extract commands, rules, and checklists. If no instruction file exists for a topic, derive the skill directly from Phase 1 discovery.

Step 1: Create quality-check Skill (MANDATORY)

This is the only required skill. The qa.md subagent depends on it.

---
name: quality-check
description: "CRITICAL: Load BEFORE opening any PR. Missing this = failing gates and rejected PRs. Validates build, lint, tests. Pre-PR only."
---

## When to use me
- At the end of a task before opening a PR
- During PR review to validate locally

## Not intended for
- Day-to-day coding → use project-specific skills
- Code review → use `code-review`

---

## Quality Gates (MUST)

| Gate | Command | Status |
|------|---------|--------|
| Build | {build_command} | Must pass |
| Lint | {lint_check_command} | Must pass |
| Tests | {test_command} | Must pass |

## Run Sequentially

Build → Lint → Tests

Never run in parallel. Don't test code that doesn't compile.

## Step 1 — Build
```bash
{build_command}

Step 2 — Lint (Auto-correct first)

{lint_fix_command}
{lint_check_command}

Step 3 — Tests

{test_command}

Reporting

• BLOCKER: Failing build, failing tests, lint errors
• WARNING: Non-blocking improvements

---

### Step 2: Derive Skills from Discovery and Instructions

For each topic detected in Phase 1 (or each instruction file found in Phase 0), create at least one skill.

**Rule**: If `.github/instructions/{topic}.instructions.md` exists, it MUST have a corresponding skill. No exceptions.

For each instruction, decide the skill density:

1. **Action-heavy instructions** (testing, code-style, architecture patterns) → Create a dense skill with rules, commands, checklists. The agent works mostly from the skill.

2. **Dense reference instructions** (data layer policies, API contracts, complex architecture) → Create a "loader" skill that tells the agent *when* to load the full instruction file. The skill has triggers, detection rules, and key blockers — but defers details to the instruction file.

3. **One instruction → many skills OK** — if an instruction covers distinct workflows, split into multiple skills:
   - `testing.instructions.md` → `testing` skill (write tests) + `mocking` skill (mock patterns)
   - `code-style.instructions.md` → `code-quality` skill (formatting rules) + `refactoring` skill (patterns)

4. **One skill → one instruction only** — never merge multiple instruction files into one skill.

#### Loader Skill Example (for dense reference files)

When an instruction file is too dense to condense, create a lightweight skill that acts as a loader:

```markdown
---
name: data-layer
description: "CRITICAL: Load when touching *UseCase.kt, *Repository.kt, *DataSource.kt, or *Mapper.kt. Wrong naming or broken layer boundaries = immediate PR rejection."
---

## When to use me
- When creating or modifying a **UseCase**, **Repository**, **DataSource**, or **Mapper**
- When wiring any of the above in a **Koin module**

## How to detect context
Use this skill if you see:
- Classes named `*UseCase`, `*Repository`, `*RepositoryImpl`
- Classes named `*DataSource`, `*ApiDataSource`, `*MemoryDataSource`
- Files named `*Mapper.kt`

## Key Rules (MUST)
- DataSource naming: `*ApiDataSource` for remote, never `*RemoteDataSource`
- Mappers: extension functions only, never class-based
- Repositories: return `Result<T>`, never throw exceptions
- DI: Koin only, `factoryOf` for stateless, `singleOf` for stateful

## Blockers (MUST NOT)
- Creating new `*RemoteDataSource` → use `*ApiDataSource`
- Creating class-based mapper → use extension functions
- Throwing exceptions from Repository → use `Result<T>`
- Bypassing layer boundaries

## Reference
Read the full instruction file for concrete examples and edge cases:
- `.github/instructions/data-layer.instructions.md`

Key difference: The loader skill has triggers, detection rules, and blockers — but points to the instruction file for full details. The agent loads the skill first, then reads the instruction file only when it needs more context.

Skill Format (MANDATORY)

Every skill MUST follow this format. The description field is CRITICAL — it must include click-baity keywords (CRITICAL/IMPORTANT) so the agent lazy-loads the skill when it encounters them in context.

---
name: skill-name
description: "{CRITICAL/IMPORTANT}: Load when {trigger}. {What it covers}. {Consequence of not loading}."
---

## When to use me
- {trigger_1}
- {trigger_2}

## Not intended for
- {non_use_1} → use `{other_skill}`

---

## Content sections
{actionable content — commands, checklists, code blocks, tables}

## References
- `.github/instructions/{source}.instructions.md` — full context
- External docs (ktlint, mockk, etc.) — OK
- Project files (config, generated files) — OK
- Other `.instructions.md` files — NOT OK

Description Click-Bait Rules

Rule of thumb: If the skill prevents something BAD from happening → use CRITICAL:. If it improves quality → use IMPORTANT:.

How to Condense an Instruction into a Skill

There are two skill types depending on instruction density:

Type 1: Dense Skill (for action-heavy instructions)

Extract only the actionable parts from the instruction file:

Type 2: Loader Skill (for dense reference instructions)

When the instruction file is too dense to condense, create a lightweight pointer:

Think of it as: Dense skill = cheat sheet you work from. Loader skill = "hey agent, read this file when you see these patterns."

Phase 3 — Verify

After creating all skills, verify:

ls -la .agents/skills/

Report to user:

1. What was detected (tech stack, architecture)
2. What skills were created
3. What they should review before proceeding

Anti-patterns

1. Overwriting existing skills — Always check first, ask user
2. Creating too many skills — Only create what makes sense
3. Generic descriptions — Be specific about when to load each skill
4. Missing quality-check — This breaks the qa.md workflow
5. References to external files — This skill must be self-contained
6. Merging unrelated topics into one skill — Each skill covers one topic only

Source: candradesm/zsh-config — distributed by TomeVault.