pdf-artifact-generation
Skill40 starsChanged 4 days agoApache-2.0View on GitHub
Use when creating or polishing any portable Markdown, HTML, or PDF artifact in Hussh, including monthly executive reports, technical papers, contributor reports, and documents generated by Codex or Claude. Use the shared Foundation formatter; reject local CSS or renderer forks.
In this repository69 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hushh-webapp/AGENTS.mdAGENTS.md
- impeccableSkill
- agent-orchestration-governanceSkill
- analytics-observability-governanceSkill
- animateSkill
- animation-vocabularySkill
- apple-designSkill
- autonomous-rca-governanceSkill
- backend-agents-operonsSkill
- backend-api-contractsSkill
- backend-runtime-governanceSkill
- backendSkill
- brandkitSkill
- client-env-paritySkill
- codex-skill-authoringSkill
- comms-communitySkill
- context-refreshSkill
- contributor-onboardingSkill
- docs-governanceSkill
- emil-design-engSkill
- find-animation-opportunitiesSkill
- founder-brief-curationSkill
- frontend-architectureSkill
- frontend-cache-coherenceSkill
- frontend-design-systemSkill
- frontend-native-surface-mapperSkill
- frontendSkill
- frontend-surface-placementSkill
- future-plannerSkill
- github-contribution-governanceSkill
- hushh-consent-mcpSkill
- hushh-icon-themeSkill
- iam-consent-governanceSkill
- imagegen-frontend-mobileSkill
- imagegen-frontend-webSkill
- improve-animationsSkill
- industrial-brutalist-uiSkill
- kai-test-account-resetSkill
- less-text-karma-jiSkill
- mcp-developer-surfaceSkill
- mobile-nativeSkill
- mobile-parity-auditSkill
- mobile-plugin-contractsSkill
- morphy-axSkill
- one-voice-governanceSkill
- oss-license-governanceSkill
- pick-ui-librarySkill
- pkm-upgrade-rehearsalSkill
- planning-boardSkill
- pr-governance-reviewSkill
- profile-uiSkill
- prototypeSkill
- puppy-one-harnessSkill
- quality-contractsSkill
- release-ios-appstoreSkill
- repo-contextSkill
- repo-operationsSkill
- review-animationsSkill
- reviewer-app-testingSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Use this path. Do not add an artifact-local stylesheet, font bundle, HTML renderer, or a second token palette.
- Very specific: line 35
Use the four published Foundation themes only: light, dark, molten-gold-light, and molten-gold.
- Distinctive: line 62
Use fact rails for a small group of key measures.
- Distinctive: line 75
Use it when leadership needs to see what moved, not merely the volume of activity.
- Distinctive: line 104
Do not simulate full bleed with negative margins, a fixed overlay, or a separate PDF merge.
- Very specific: line 118
Run the collection only with read-only GitHub access and preserve the resulting JSON beside the requested artifact.
- Distinctive: line 124
Never derive hours, compensation, or individual performance from calendar events, commits, or diff churn.
- Distinctive: line 136
Before sharing, inspect rendered pages—not just Markdown or HTML—for:
- Distinctive: line 140
no clipped type, table overflow, orphaned profiles, or accidental empty pages.
- Very specific: line 148
Run python3 scripts/ops/verify_pdf_artifact_contract.py whenever changing the common artifact path or a cross-platform bridge.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Portable PDF artifact generation
This is the platform-neutral behavioral source for Hussh PDF artifacts. Codex and Claude discover it through thin bridges; edit this file when the shared practice changes.
Canonical implementation
| Concern | Source of truth |
| Tokens | hushh-webapp/app/globals.css |
| Formatter profiles and print geometry | hushh-webapp/lib/morphy-ux/pdf-document-formatter.mjs |
| Markdown, semantic directives, HTML, and PDF export | hushh-webapp/scripts/reports/export-markdown-pdf.mjs |
| Calendar-ready GitHub evidence collection | .agents/skills/pdf-artifact-generation/scripts/collect_github_month.py |
| Source-linked contributor calendar Markdown | .agents/skills/pdf-artifact-generation/scripts/render_github_month_calendar.py |
| Codex routing bridge | .agents/skills/founder-brief-curation/references/pdf-artifact-generation.md |
| Claude discovery bridge | .claude/skills/pdf-artifact-generation/SKILL.md |
Use this path. Do not add an artifact-local stylesheet, font bundle, HTML renderer, or a second token palette. The portable artifact is a consumer of the app Foundation, not an independently branded document system.
Choose a profile before authoring
technical: precise implementation notes and reference material.partner: concise external technical material.founder: narrative architecture and founder-facing briefs.executive: decision-oriented audits or leadership reviews; supports a full-bleed cover.
Use the four published Foundation themes only: light, dark,
molten-gold-light, and molten-gold. Never hard-code an accent or approximate a
theme in report Markdown or CSS.
For board, chairman or senior partner technology reviews, follow executive-technology-readout.md for audience, evidence density and chart selection. Keep detailed receipts in supporting evidence.
Author semantic content, not presentation escapes
The renderer accepts Markdown plus narrow semantic directives. Use a directive only when the information itself has the stated meaning:
<!-- pdf:table=metrics -->
<!-- pdf:table=scorecard -->
<!-- pdf:table=evidence -->
<!-- pdf:table=ledger -->
<!-- pdf:profile-start -->
<!-- pdf:profile-end -->
<!-- pdf:table=calendar -->
<!-- pdf:table=calendar-list -->
<!-- pdf:callout=decision -->
<!-- pdf:callout-end -->
<!-- pdf:page-break -->Use fact rails for a small group of key measures; use a ledger or evidence table only for comparisons and traceability. Do not recreate decorative boxed/zebra dashboards, badge stacks, or per-report visual grammar. Keep one person’s executive profile together.
pdf:table=calendar is a seven-day month grid, not a productivity score. Use weekday
headers and cells in the form date :: primary event measure :: optional supporting detail;
use — for an intentional blank. For an executive GitHub audit, the detail is a concise,
linked representative PR or issue title; include its head-commit link where available. State the
metric legend and timezone in nearby prose, and label merge/open/issue timestamps as source-event
dates rather than claimed work dates.
pdf:table=calendar-list is the executive default for a GitHub work-progress calendar: one
source-linked row per active local date with Local date | Recorded event | Audited delivery.
Use it when leadership needs to see what moved, not merely the volume of activity. Account for
the entire month: render every contiguous no-activity interval as a muted dated row rather than
leaving unexplained gaps.
Executive cover contract
pdf:cover is a physical page, not an inset dark card. It is available only with
--profile executive and has three non-negotiable rules:
- It is the first semantic block in the source.
- It has exactly one start and end directive.
- It is immediately followed by an explicit page break.
<!-- pdf:cover-start -->
Cover thesis, factual metric rail, and decision callout.
<!-- pdf:callout=decision -->
Decision text.
<!-- pdf:callout-end -->
<!-- pdf:cover-end -->
<!-- pdf:page-break -->The shared exporter maps this to the named pdf-cover A4 page with margin: 0; normal
document pages retain the formatter’s reading margins. Any white perimeter, corner bar,
or visible page background around a cover is a release blocker, not a stylistic choice.
Do not simulate full bleed with negative margins, a fixed overlay, or a separate PDF merge.
Monthly executive reporting cadence
For a recurring GitHub report, collect a fresh, UTC-bounded evidence file before writing the artifact. Use the portable collector rather than a copied one-off script:
python3 .agents/skills/pdf-artifact-generation/scripts/collect_github_month.py \
--org hushh-labs --month YYYY-MM --timezone America/Los_Angeles \
--person 'Display name=github-login' \
--output tmp/github-activity-YYYY-MM.jsonRun the collection only with read-only GitHub access and preserve the resulting JSON beside
the requested artifact. --timezone is mandatory: it defines the local calendar, source
window, and every rendered date label; never silently fall back to UTC or the machine timezone.
The collector fails rather than silently truncating a GitHub Search
cohort above the API’s 1,000-result cap. Then follow the focused source and interpretation
rules in monthly-executive-report-cadence.md.
Never derive hours, compensation, or individual performance from calendar events, commits,
or diff churn; use them to identify delivery and the review/validation surface.
Render and verify
cd hushh-webapp
node hushh-webapp/scripts/reports/export-markdown-pdf.mjs \
--input <artifact.md> --output <artifact.pdf> --html <artifact.html> \
--theme light --profile executiveBefore sharing, inspect rendered pages—not just Markdown or HTML—for:
- physical page 1 corners matching the cover ground with no white perimeter;
- page 2 and later retaining readable margins;
- no clipped type, table overflow, orphaned profiles, or accidental empty pages;
- hierarchy that moves from thesis to evidence to individual attention to sources;
- embedded Inter body typography and Foundation-derived colors in the chosen theme;
- source links that are shareable rather than machine-local paths.
For monthly reports, also verify that the calendar has every day in the declared UTC month, uses only collected event types, includes its legend, and does not split across pages.
Run python3 scripts/ops/verify_pdf_artifact_contract.py whenever changing the common
artifact path or a cross-platform bridge. Render at least one representative executive
fixture after geometry changes and retain only the requested artifact outputs.
Cross-platform maintenance
The canonical .agents/skills/pdf-artifact-generation/SKILL.md file is the only portable behavior contract. A Codex bridge may preserve
governed routing metadata, and a Claude bridge may preserve discovery frontmatter, but
neither may restate this procedure. Native discovery resolves to this source.
The historical morphy-pdf alias is retired; do not recreate a private renderer
or stylesheet.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

