skills-portfolio-scaffold

---
name: skills-portfolio-scaffold
description: Use when a user wants to publish their own Hermes skills as a categorized, ranked, sortable skills portfolio — discoverable by both humans (sortable site) and agents (structured index) — or says "set up a skills portfolio" / "make my skills installable".
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [skills-portfolio, scaffolding, skills-index, static-site]
    related_skills: [hallmark-readme, skill-publish, portfolio-upkeep]
---

# skills-portfolio-scaffold

## Overview

Scaffold a skills portfolio repository with the three-surface architecture: a monorepo of skills, a `skills-index.json` for agent-parseable metadata, a sortable static site, and CI validation. This is the meta-skill that reproduces the portfolio structure for anyone who wants to publish their own skills — under their own name and branding, never a clone of this one.

## When to Use

- The user wants to publish their own Hermes skills as a portfolio.
- The user wants a structured, categorized, ranked collection of skills (not just a flat directory).
- The user wants their skills to be discoverable by both humans (sortable site) and agents (structured index).
- The user says "set up a skills portfolio", "I want to publish my skills", or "make my skills installable".

## Prerequisites

- Git installed and configured
- A GitHub account (for the public shopfront)
- Hermes Agent installed (for `hermes skills install` to work for end users)
- Skills to publish — at least one `SKILL.md` with frontmatter

## Workflow

### Step 0: Name the portfolio

Before scaffolding anything, ask the user for three things: what they want their portfolio **called** (e.g. "Jane's Automation Skills," not "Hermes Skills Portfolio" — this is their shopfront, not a copy of this one), their **name or handle** as it should appear in the README/site footer, and a one-sentence **tagline**. Use their answers everywhere `portfolio.name` / `portfolio.owner` / `portfolio.tagline` appear in Step 2 — never leave a placeholder value or default to "Hermes" in the generated output.

### Step 1: Create the repo structure

```
<portfolio-name>/
├── README.md                    ← the shopfront (Hallmark quality)
├── skills-index.json            ← single source of truth
├── skills-index.schema.json     ← schema for the index
├── LICENSE                      ← MIT recommended
├── .gitignore
├── docs/adr/                    ← architecture decisions
├── skills/                      ← one directory per skill
│   └── <skill-name>/
│       ├── SKILL.md
│       └── README.md
└── site/                        ← sortable static site
    ├── index.html
    ├── styles.css
    └── app.js
```

### Step 2: Create skills-index.json

The index is the single source of truth. Both the README and the static site render from it. Schema:

```json
{
  "version": "1.0.0",
  "generated_at": "ISO-8601 timestamp",
  "portfolio": {
    "name": "Your Portfolio Name",
    "owner": "Your Name",
    "tagline": "One sentence. No filler.",
    "total_skills": 0,
    "github_url": "https://github.com/your-user/your-portfolio"
  },
  "categories": {
    "devops": { "name": "DevOps", "description": "...", "skill_count": 0 },
    "frontend": { "name": "Frontend", "description": "...", "skill_count": 0 }
  },
  "skills": [
    {
      "name": "skill-name",
      "category": "devops",
      "tier": "core",
      "description": "One line. What agent + skill delivers.",
      "install_url": "https://github.com/your-user/your-portfolio/blob/main/skills/skill-name/SKILL.md",
      "path": "skills/skill-name",
      "usage": { "hub_installs": 0, "github_clones": 0, "stars": 0 },
      "recency": "2026-01-01",
      "source": "new",
      "source_attribution": ""
    }
  ]
}
```

### Step 3: Assign usefulness tiers

Every skill gets one of three tiers at publish time:

| Tier | Meaning |
|---|---|
| `core` | Broadly empowering, nearly any user benefits |
| `featured` | Highly useful within a category |
| `utility` | Useful for specific workflows |

This is a curated judgment, not a metric. It's the day-one ranking — usage data enriches it later but never replaces it.

### Step 4: Create the static site

The `site/` directory contains a self-contained HTML/CSS/JS app that:
- Fetches `skills-index.json` on page load
- Renders skill cards in a responsive grid
- Supports sorting (tier-then-usage default, plus usage/recency/category/alphabetical)
- Supports filtering (category, tier) and search
- Uses OKLCH colors, a real font pairing, no AI-slop patterns

See the portfolio's own `site/` directory for a working reference implementation.

### Step 5: Add CI validation

Create `.github/workflows/validate.yml` (or `.forgejo/workflows/validate.yml` for Forgejo):

```yaml
name: validate
on: push
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate SKILL.md frontmatter
        run: |
          for skill_md in skills/*/SKILL.md; do
            name=$(grep -m1 '^name:' "$skill_md" | sed 's/^name:[[:space:]]*//')
            [ -z "$name" ] && echo "FAIL: $skill_md missing name" && exit 1
          done
```

### Step 6: Write the README

The portfolio README is the shopfront. It should include:
- A one-sentence tagline (no filler)
- Install instructions for individual skills
- A categories table
- The ranking explanation (tiers + usage)
- The repo structure
- Links to ADRs (if any)
- License info

### Step 7: Publish

```bash
git init
git add -A
git commit -m "Initial portfolio scaffold"
git remote add origin https://github.com/<user>/<portfolio-name>.git
git push -u origin main
```

### Step 8: Add skills incrementally

Each new skill:
1. Create `skills/<skill-name>/SKILL.md` with frontmatter
2. Create `skills/<skill-name>/README.md` (Hallmark quality)
3. Add an entry to `skills-index.json`
4. Commit and push
5. The CI validates the frontmatter

## Skill Entry Requirements

Every skill in the portfolio must have:

| Requirement | Where | Notes |
|---|---|---|
| `SKILL.md` with frontmatter | `skills/<name>/SKILL.md` | `name`, `description`, `version` minimum |
| `README.md` | `skills/<name>/README.md` | What it does, install, how to use, example |
| Index entry | `skills-index.json` | name, category, tier, description, install_url, path, source |

## Site Features

The portfolio static site includes:
- Dark mode default with light toggle (localStorage persistence)
- Sortable skill cards (by tier+usage, usage, recency, category, alphabetical)
- Category and tier filters with filter chips
- Search with keyboard shortcut (`/`)
- **Detail page overlay**: clicking a skill opens a full page with:
  - "What it does" (user-facing description)
  - "How an agent uses it" (agent-facing use cases)
  - SKILL.md tab (raw markdown rendered for reading)
  - README tab (raw markdown rendered for reading)
  - Install command with copy-to-clipboard
  - Close button (X icon), Esc key, click-outside-to-close
  - Shareable URL hash: `#skill/<name>`
- Category distribution bar
- Back-to-top button
- Toast notifications
- Keyboard: `/` search, `Esc` close detail, `t` toggle theme

### GitHub Pages deployment

GitHub Pages only serves from `/` or `/docs`. Deploy:
1. Copy site files + skills-index.json into `docs/`
2. Settings → Pages → Source → Deploy from branch → `main` → `/docs`
3. Site live at `https://<username>.github.io/<repo-name>/`

### skills-index.json enrichment

Each skill entry should include `agent_use`, `user_use`, `skillmd_content`, and `readme_content` fields so the detail page can show all content without fetching individual files.

## Common Pitfalls

1. **Index drift.** If you add a skill directory but forget to add an entry to `skills-index.json`, the site won't show it and the CI should warn. Keep them in sync.
2. **Relative links in README.** Links like `../other-skill/` break when a skill is published to its own repo via `skill-publish`. Use absolute URLs for cross-skill references.
3. **Tier inflation.** Don't mark everything `core`. If all skills are core, the tier is meaningless. Reserve `core` for skills that nearly any user benefits from.
4. **No categories.** Every skill must belong to a category. Uncategorized skills break the filter UI and the agent-parseable index.
5. **Invented usage data.** Start all usage counts at 0. Don't fabricate install numbers — they'll be overwritten by real data once the portfolio has traffic, and fake numbers erode trust.
6. **`skills-index.json` too large.** Embedding full SKILL.md and README.md content in the index makes it large (500KB+ for 50 skills). This is acceptable for a static site — it loads once and enables instant detail page rendering without per-skill fetches.
7. **`docs/` vs `site/` drift.** When you update site files, always copy them to `docs/` too. The `docs/` directory is what GitHub Pages serves. Use a sync script or the portfolio-upkeep skill.

## Verification Checklist

- [ ] `skills-index.json` validates against `skills-index.schema.json` and every skill directory under `skills/` has a matching index entry
- [ ] Every skill entry has a `tier` (`core`/`featured`/`utility`) and a `category`, and not everything is tagged `core`
- [ ] `site/` files are mirrored into `docs/` (what GitHub Pages actually serves)
- [ ] The CI validation workflow runs and fails a skill missing `name:` in its frontmatter
- [ ] All `usage` counts in newly added entries start at 0 — no fabricated install/star numbers

# skills-portfolio-scaffold



Scaffold a publishable skills portfolio with categorized, ranked, sortable skills and a static site — named and branded as *your own*, not a copy of this one.



## What it does



The agent asks what you want your portfolio called, then creates a portfolio repo structure for your skills: a monorepo with one directory per skill, a `skills-index.json` that serves as the single source of truth (for both humans and agents), a sortable static site, CI validation, and a Hallmark-quality README. This is the meta-skill that reproduces the portfolio structure so anyone can publish their own skills the same way — under their own name.



## Install



```bash

hermes skills install https://raw.githubusercontent.com/THEROCKSSS/hermes-skills-portfolio/main/skills/skills-portfolio-scaffold/SKILL.md

```



## How to use



```

"Set up a skills portfolio for my Hermes skills"

```



The agent:

1. Creates the repo structure (README, skills-index.json, site/, docs/adr/, skills/, CI workflow)

2. Sets up the JSON schema for the index

3. Generates the sortable static site (HTML/CSS/JS)

4. Creates the CI validation workflow

5. Shows you how to add skills incrementally



## What you get



| Component | Purpose |

|---|---|

| `skills-index.json` | Single source of truth — agents parse this, the site renders from it |

| `site/` | Sortable, filterable static site (sort by tier, usage, category, recency) |

| `skills/<name>/` | One directory per skill, each with SKILL.md + README.md |

| CI workflow | Validates every SKILL.md has required frontmatter |

| README.md | The shopfront — install instructions, categories, ranking explanation |



## The ranking model



Every skill gets a usefulness tier at publish time:



- **Core** — broadly empowering, nearly any user benefits

- **Featured** — highly useful within a category

- **Utility** — useful for specific workflows



Default sort: tier (Core → Featured → Utility), then usage within tier. Usage data accumulates over time from hub installs and GitHub clones.



## Example



```

User: "I have 15 Hermes skills I want to publish as a portfolio."



Agent:

  1. Creates the repo structure with skills-index.json schema

  2. Generates the sortable static site

  3. For each of the 15 skills: creates skills/<name>/ with SKILL.md + README.md

  4. Adds each skill to skills-index.json with category + tier

  5. Creates the CI workflow

  6. Returns: "Portfolio scaffolded. Push to GitHub when ready."



User pushes to GitHub → strangers can browse the site, install individual skills,

and agents can read skills-index.json to recommend skills.

```