设计与创意 · SKILL.md

create-glyph

create-glyph

【设计与创意】Create R-based pictogram glyphs for skill, agent, or team icons in the visualization layer. Covers concept sketching, ggplot2 layer composition using the primitives library, color strategy, registration in the appropriate glyph mapping file and manifest, rendering via the build pipeline, and visual verification of the neon-glow output. Use when a new…

独立 GitHub 快照 · 自动分类 · 以原作者文档为准

Ppjt222 / agent-almanacMIT

技能说明

GitHub

name: create-glyph locale: caveman source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Create R-based pictogram glyphs for skill, agent, or team icons in the visualization layer. Covers concept sketching, ggplot2 layer composition using the primitives library, color strategy, registration in the appropriate glyph mapping file and manifest, rendering via the build pipeline, and visual verification of the neon-glow output. Use when a new entity has been added and needs a visual icon for the force-graph visualization, an existing glyph needs replacement, or when batch-creating glyphs for a new domain. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "2.0" domain: design complexity: intermediate language: R tags: design, glyph, pictogram, icon, ggplot2, visualization, neon

Create Glyph

Make R-based pictogram glyphs for skill, agent, or team icons in viz/ visualization layer. Each glyph is pure-ggplot2 function. Draws recognizable shape on 100x100 canvas. Rendered with neon glow to transparent-background WebP.

When Use

New skill, agent, or team added. Needs visual icon
Existing glyph needs replacement or redesign
Batch-creating glyphs for new skills domain
Prototyping visual metaphors for entity concepts

Inputs

Required: Entity type — skill, agent, or team
Required: Entity ID (e.g., create-glyph, mystic, r-package-review) and domain (for skills)
Required: Visual concept — what glyph should depict
Optional: Reference glyph to study for complexity level
Optional: Custom --glow-sigma value (default: 4)

Steps

Step 1: Concept — Design the Visual Metaphor

Identify entity being iconified. Pick visual metaphor.

Read entity's source file. Understand core concept:
- Skills: skills/<id>/SKILL.md
- Agents: agents/<id>.md
- Teams: teams/<id>.md
Pick metaphor type:
- Literal object: flask for experiments, shield for security
- Abstract symbol: arrows for merging, spirals for iteration
- Composite: combine 2-3 simple shapes (e.g., document + pen)
Reference existing glyphs for complexity calibration:

Complexity Tiers:
+----------+--------+-------------------------------------------+
| Tier     | Layers | Examples                                  |
+----------+--------+-------------------------------------------+
| Simple   | 2      | glyph_flame, glyph_heartbeat              |
| Moderate | 3-5    | glyph_document, glyph_experiment_flask    |
| Complex  | 6+     | glyph_ship_wheel, glyph_bridge_cpp        |
+----------+--------+-------------------------------------------+

Pick function name: glyph_<descriptive_name> (snake_case, unique)

Got: Clear mental sketch of shape with 2-6 planned layers.

If fail: Concept too abstract? Fall back to related concrete object. Review existing glyphs in same domain for inspiration.

Step 2: Compose — Write the Glyph Function

Write R function producing ggplot2 layers.

Function signature (immutable contract):

glyph_<name> <- function(cx, cy, s, col, bright) {
  # cx, cy = center coordinates (50, 50 on 100x100 canvas)
  # s = scale factor (1.0 = fill ~70% of canvas)
  # col = domain color hex (e.g., "#ff88dd" for design)
  # bright = brightened variant of col (auto-computed by renderer)
  # Returns: list() of ggplot2 layers
}

Apply scale factor * s to ALL dimensions for consistent scaling:

r <- 20 * s        # radius
hw <- 15 * s       # half-width
lw <- .lw(s)       # line width (default base 2.5)
lw_thin <- .lw(s, 1.2)  # thinner line width

Build geometry using available primitives:

Geometry	Usage
`ggplot2::geom_polygon(data, .aes(x, y), ...)`	Filled shapes
`ggplot2::geom_path(data, .aes(x, y), ...)`	Open lines/curves
`ggplot2::geom_segment(data, .aes(x, xend, y, yend), ...)`	Line segments, arrows
`ggplot2::geom_rect(data, .aes(xmin, xmax, ymin, ymax), ...)`	Rectangles
`ggforce::geom_circle(data, .aes(x0, y0, r), ...)`	Circles

Apply color strategy:

Alpha Guide:
+----------------------+------------+--------------------------+
| Purpose              | Alpha      | Example                  |
+----------------------+------------+--------------------------+
| Large fill (body)    | 0.08-0.15  | hex_with_alpha(col, 0.1) |
| Medium fill (accent) | 0.15-0.25  | hex_with_alpha(col, 0.2) |
| Small fill (detail)  | 0.25-0.35  | hex_with_alpha(bright, 0.3) |
| Outline stroke       | 1.0        | color = bright           |
| Secondary stroke     | 1.0        | color = col              |
| No fill              | ---        | fill = NA                |
+----------------------+------------+--------------------------+

Return flat list() of layers. Renderer iterates and wraps each with glow.
Place function in right primitives file by entity type:
- Skills: domain-grouped across 19 primitives files:
  - primitives.R — bushcraft, compliance, containerization, data-serialization, defensive
  - primitives_2.R — devops, general, git, mcp-integration
  - primitives_3.R — mlops, observability, PM, r-packages, reporting, review, web-dev, esoteric, design
  - More primitives_4.R through primitives_19.R for newer domains
- Agents: viz/R/agent_primitives.R
- Teams: viz/R/team_primitives.R

Got: Working R function returning list of 2-6 ggplot2 layers.

If fail: ggforce::geom_circle errors? Confirm ggforce installed. Coords off? Canvas is 100x100 with (0,0) at bottom-left. Test function interactively:

source("viz/R/utils.R"); source("viz/R/primitives.R")  # etc.
layers <- glyph_<name>(50, 50, 1.0, "#ff88dd", "#ffa8f0")
p <- ggplot2::ggplot() + ggplot2::coord_fixed(xlim=c(0,100), ylim=c(0,100)) +
     ggplot2::theme_void()
for (l in layers) p <- p + l
print(p)

Step 3: Register — Map Entity to Glyph

Add entity-to-glyph mapping in right glyph mapping file.

For skills:

Open viz/R/glyphs.R
Find comment section for target domain (e.g., # -- design (3))
Add entry in alphabetical order within domain block:
```
"skill-id" = "glyph_function_name",
```
Update domain count in comment if applicable

For agents:

Open viz/R/agent_glyphs.R
Find alphabetical position in AGENT_GLYPHS
Add entry:
```
"agent-id" = "glyph_function_name",
```

For teams:

Open viz/R/team_glyphs.R
Find alphabetical position in TEAM_GLYPHS
Add entry:
```
"team-id" = "glyph_function_name",
```
Verify no duplicate ID exists in target list

Got: Right *_GLYPHS list has new mapping.

If fail: Build later reports "No glyph mapped"? Double-check entity ID exactly matches one in manifest and registry.

Step 4: Manifest — Add Icon Entry

For skills: viz/data/icon-manifest.json

{
  "skillId": "skill-id",
  "domain": "domain-name",
  "prompt": "<domain basePrompt>, <descriptors>, dark background, vector art",
  "seed": <next_seed>,
  "path": "public/icons/cyberpunk/<domain>/<skill-id>.webp",
  "status": "pending"
}

For agents: viz/data/agent-icon-manifest.json

{
  "agentId": "agent-id",
  "prompt": "<agent-specific descriptors>, dark background, vector art",
  "seed": <next_seed>,
  "path": "public/icons/cyberpunk/agents/<agent-id>.webp",
  "status": "pending"
}

For teams: viz/data/team-icon-manifest.json

{
  "teamId": "team-id",
  "prompt": "<team-specific descriptors>, dark background, vector art",
  "seed": <next_seed>,
  "path": "public/icons/cyberpunk/teams/<team-id>.webp",
  "status": "pending"
}

Got: Valid JSON with new entry placed among type siblings.

If fail: Validate JSON syntax. Common mistakes: trailing comma after last array element, missing quotes.

Step 5: Render — Generate the Icon

Run icon pipeline to render new glyph. Always use build.sh as entry point — it handles platform detection and R binary selection. See render-icon-pipeline for full flag reference and pipeline architecture.

# From project root — renders all palettes, standard + HD, skips existing icons
bash viz/build.sh --only <domain> --skip-existing          # skills
bash viz/build.sh --type agent --only <id> --skip-existing # agents
bash viz/build.sh --type team --only <id> --skip-existing  # teams

# Dry run first:
bash viz/build.sh --only <domain> --dry-run

build.sh runs full pipeline (palette → data → manifest → render → terminal glyphs). Non-render steps add ~10 seconds but keep all data current.

Output locations:

Skills: viz/public/icons/<palette>/<domain>/<skill-id>.webp
Agents: viz/public/icons/<palette>/agents/<agent-id>.webp
Teams: viz/public/icons/<palette>/teams/<team-id>.webp

Got: Log shows OK: <entity> (seed=XXXXX, XX.XKB). WebP file exists.

If fail:

"No glyph mapped" — Step 3 mapping missing or typo
"Unknown domain" — Domain not in get_palette_colors() in palettes.R
R package errors — Run install.packages(c("ggplot2", "ggforce", "ggfx", "ragg", "magick")) first
Rendering crashes? Test glyph function interactively (see Step 2 fallback)

Step 6: Verify — Visual Inspection

Check rendered output meets quality standards.

Verify file exists and has reasonable size:

ls -la viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp
# Expected: 15-80 KB typical range

Open WebP in image viewer. Check:
- Shape reads clearly at full size (1024x1024)
- Neon glow present but not overpowering
- Background transparent (no black/white rectangle)
- No clipping at canvas edges
Check at small sizes (icon renders at ~40-160px in force graph):
- Shape stays recognizable
- Detail does not turn to noise
- Glow does not overwhelm shape

Got: Clear, recognizable pictogram with even neon glow on transparent background.

If fail:

Glow too strong: re-render with --glow-sigma 2 (default is 4)
Glow too weak: re-render with --glow-sigma 8
Shape unreadable small? Simplify glyph (fewer layers, bolder strokes, bump .lw(s, base) base value)
Clipping at edges? Shrink shape dimensions or shift center

Step 7: Iterate — Refine if Needed

Adjust and re-render.

Common adjustments:
- Bolder strokes: bump .lw(s, base) — try base = 3.0 or 3.5
- More visible fill: bump alpha from 0.10 to 0.15-0.20
- Shape proportions: tune multipliers on s (e.g., 20 * s -> 24 * s)
- Add/remove detail layers: keep total layers 2-6 for best results

Re-render after changes:

# Delete the existing icon first, then re-render
rm viz/public/icons/cyberpunk/<type-path>/<entity-id>.webp
# Use the appropriate build command from Step 5

Satisfied? Verify manifest status shows "done". Build script updates it on success.

Got: Final icon passes all verification checks from Step 6.

If fail: After 3+ iterations glyph still reads poorly? Consider completely different visual metaphor (back to Step 1).

Reference

Domain and Entity Color Palettes

All domain colors (for skills) in viz/R/palettes.R (single source of truth). Agent and team colors also in palettes.R. Cyberpunk palette (hand-tuned neon colors) in get_cyberpunk_colors(). Viridis-family palettes auto-generated via viridisLite.

Look up color:

source("viz/R/palettes.R")
get_palette_colors("cyberpunk")$domains[["design"]]   # skill domain
get_palette_colors("cyberpunk")$agents[["mystic"]]     # agent
get_palette_colors("cyberpunk")$teams[["tending"]]     # team

Adding new domain? Add to three places in palettes.R:

PALETTE_DOMAIN_ORDER (alphabetical)
get_cyberpunk_colors() domains list
Run bash viz/build.sh to regenerate palettes, data, manifests

Glyph Function Catalog

See full catalog of available glyph functions in primitives source files:

Skills: viz/R/primitives.R through viz/R/primitives_19.R (domain-grouped)
Agents: viz/R/agent_primitives.R
Teams: viz/R/team_primitives.R

Helper Functions

Function	Signature	Purpose
`.lw(s, base)`	`(scale, base=2.5)`	Scale-aware line width
`.aes(...)`	alias for `ggplot2::aes`	Shorthand aesthetic mapping
`hex_with_alpha(hex, alpha)`	`(string, 0-1)`	Add alpha to hex color
`brighten_hex(hex, factor)`	`(string, factor=1.3)`	Brighten a hex color
`dim_hex(hex, factor)`	`(string, factor=0.4)`	Dim a hex color

Checks

Pitfalls

Forgetting * s: Hard-coded pixel values break when scale changes. Always multiply by s.
Canvas origin confusion: (0,0) is bottom-left, not top-left. Higher y values move UP.
Double glow: Renderer already applies ggfx::with_outer_glow() to every layer. Do NOT add glow inside glyph function.
Too many layers: Each layer gets individual glow wrapping. More than 8 layers → slow rendering, noisy visuals.
Mismatched IDs: Entity ID in glyph mapping, manifest, registry must all match exactly.
JSON trailing commas: Manifest is strict JSON. No trailing comma after last array element.
Missing domain color: Domain not in get_cyberpunk_colors() in palettes.R? Rendering errors. Add color first, then regenerate.
Wrong primitives file: Skills in domain-grouped primitives*.R, agents in agent_primitives.R, teams in team_primitives.R.

安装技能

TERMINAL

npx skills add pjt222/agent-almanac --skill create-glyph

复制命令到本地终端执行；安装前请先审查源代码和许可证。

ZIP · 完整技能目录，含资源与许可证

SKILL.md · 仅技能说明原文

仓库 Star: 未同步
许可证: MIT
版本 / 分支: HEAD · 57c07e1d
仓库更新时间: 未同步

安装前，请检查技能脚本与权限。

源代码