{"id":"c9153abd-1271-4219-b2fd-4a1c9256a48c","shortId":"N4c3jK","kind":"skill","title":"skillfold-context","tagline":"Context about the Skillfold project, its architecture, and design principles.","description":"# Skillfold Project Context\n\nYou are working on Skillfold, a configuration language and compiler for building multi-agent AI pipelines. The vision is a widely adopted, agent-first tool where agents author the config, agents consume the output, and humans provide direction.\n\n## What Skillfold Does\n\nSkillfold compiles YAML config into standard SKILL.md files per the Agent Skills open standard. It handles:\n\n1. **Skill Composition** - Atomic skills (referenced by path) are combined into composed skills by concatenating their SKILL.md bodies. Composition is recursive. Skills are split into `atomic` and `composed` sub-sections.\n2. **Team Flow** - Agents are wired into typed execution flows with conditional routing, loops, and parallel map. The flow compiles into an orchestrator skill. Flow and orchestrator live under the `team` config section.\n3. **State Validation** - A typed state schema validates that reads/writes are consistent across the flow. State is a top-level section, independently importable.\n4. **Orchestrator Generation** - The compiler generates a structured execution plan from the team flow definition and appends it to the orchestrator skill.\n\n## Config Structure\n\nFour top-level sections: `resources`, `skills`, `state`, `team`.\n\n- `resources` - Resource declarations mapping group names to namespace URLs for state location validation and orchestrator URL resolution\n- `skills.atomic` - Path references to atomic skill directories (local or GitHub URLs)\n- `skills.composed` - Composition declarations combining atomic skills into agents\n- `state` - Typed state schema with custom types, primitives, lists, and external locations\n- `team.orchestrator` - Optional skill name to append generated plan to\n- `team.flow` - Directed execution flow with conditional routing, loops, and parallel map\n\nImports pull in `resources`, `skills`, and `state`, ignore `team`.\n\n## Architecture\n\nThe compiler pipeline is: parse config -> resolve skill paths (local + remote) -> compile compositions -> validate state -> validate flow -> generate orchestrator.\n\nThe codebase is TypeScript (strict, ESM modules). Key modules:\n- `src/config.ts` - YAML parsing, config types, validation\n- `src/state.ts` - State schema parsing, type system, location validation\n- `src/graph.ts` - Flow parsing, validation (skills, state, conflicts, cycles)\n- `src/orchestrator.ts` - Orchestrator SKILL.md generation from flow\n- `src/resolver.ts` - Reads SKILL.md files from skill directories and GitHub URLs\n- `src/remote.ts` - GitHub URL parsing and remote skill fetching\n- `src/compiler.ts` - Recursive composition, orchestrator integration\n- `src/visualize.ts` - Mermaid flowchart generation with composition lineage\n- `src/list.ts` - Pipeline introspection (skillfold list)\n- `src/init.ts` - skillfold init scaffolding\n- `src/errors.ts` - ConfigError, ResolveError, CompileError, GraphError\n- `src/cli.ts` - CLI entry point\n\n## Key Design Principles\n\n- Single source of truth - the pipeline config owns composition, state, and topology\n- Compile to the standard - output is plain SKILL.md files\n- Skills all the way down - an agent is just a skill in a flow\n- Separation of concerns - capability in skills, topology in team flow, state in schema\n- Validated at compile time - type mismatches and broken references are compiler errors\n\n## What's Implemented\n\nAll compiler features are working: skill composition with atomic/composed sub-sections, state schema, flow validation, map subgraph validation, when-clause parsing, orchestrator generation, spec-compliant output, URL-based skill references (with private repo auth via GITHUB_TOKEN), pipeline imports, graph visualization with full composition lineage and interactive HTML output (`skillfold graph --html`), `skillfold init`, `skillfold adopt`, `skillfold validate`, `skillfold list`, `--check` for CI integration, async flow nodes for external agents, top-level resource declarations with compile-time location path validation (skill-level resources deprecated but backward compatible), sub-flow imports for nested pipeline composition, npm skill search (`skillfold search`), `npm:` prefix resolution for skill imports, local config overrides (`skillfold.local.yaml`), built-in state integrations for GitHub services (issues, discussions, pull requests), VitePress documentation site with live demo and GitHub Pages deployment, skill publishing guide, multi-platform compilation targets (`--target claude-code`, `--target agent-teams`, `--target cursor`, `--target windsurf`, `--target codex`, `--target copilot`, `--target gemini`, `--target goose`, `--target roo-code`, `--target kiro`, `--target junie`), `agentConfig` with full Claude Code frontmatter parity (including `mcpServers` and `skills` fields), and `skillfold run` for executing pipeline flows via agent spawning (`--spawner cli|sdk`) with conditional routing, loops, parallel map execution, error handling (retry/skip/abort), step timing, checkpoint-based resume, and state backend integration for GitHub services. The `SdkSpawner` uses `@anthropic-ai/claude-agent-sdk` (optional peer dependency) to give spawned agents full tool access. The `--target agent-teams` output generates skills, agents, and a `start-team.md` bootstrap command for Claude Code Agent Teams. Published on npm as `skillfold` (v1.23.0). 858 tests across 168 suites, CI on GitHub Actions. The project self-hosts its own dev team via `skillfold.yaml`.\n\n## What's Next\n\nFeatures driven by user demand.","tags":["skillfold","context","byronxlg","agent-framework","agent-skills","ai-agents","claude-code","compiler","multi-agent","orchestrator","pipeline","skill-composition"],"capabilities":["skill","source-byronxlg","skill-skillfold-context","topic-agent-framework","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-compiler","topic-multi-agent","topic-orchestrator","topic-pipeline","topic-skill-composition","topic-typescript","topic-yaml"],"categories":["skillfold"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/byronxlg/skillfold/skillfold-context","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add byronxlg/skillfold","source_repo":"https://github.com/byronxlg/skillfold","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 6 github stars · SKILL.md body (5,486 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:14:27.877Z","embedding":null,"createdAt":"2026-05-18T13:22:08.385Z","updatedAt":"2026-05-18T19:14:27.877Z","lastSeenAt":"2026-05-18T19:14:27.877Z","tsv":"'/claude-agent-sdk':674 '1':76 '168':713 '2':107 '3':140 '4':164 '858':710 'access':684 'across':152,712 'action':718 'adopt':39,504 'agent':31,41,45,49,70,110,232,409,518,598,640,681,688,693,702 'agent-first':40 'agent-team':597,687 'agentconfig':620 'ai':32,673 'anthrop':672 'anthropic-ai':671 'append':180,250 'architectur':10,274 'async':513 'atom':79,101,218,229 'atomic/composed':453 'auth':482 'author':46 'backend':663 'backward':537 'base':476,659 'bodi':93 'bootstrap':697 'broken':437 'build':28 'built':563 'built-in':562 'capabl':420 'check':509 'checkpoint':658 'checkpoint-bas':657 'ci':511,715 'claud':594,623,700 'claude-cod':593 'claus':466 'cli':376,643 'code':595,615,624,701 'codebas':295 'codex':605 'combin':85,228 'command':698 'compat':538 'compil':26,61,126,168,276,286,394,432,440,446,526,590 'compile-tim':525 'compileerror':373 'compliant':472 'compos':87,103 'composit':78,94,226,287,351,359,390,451,492,546 'concaten':90 'concern':419 'condit':118,259,646 'config':48,63,138,186,280,306,388,559 'configerror':371 'configur':23 'conflict':323 'consist':151 'consum':50 'context':3,4,16 'copilot':607 'cursor':601 'custom':238 'cycl':324 'declar':199,227,523 'definit':178 'demand':737 'demo':579 'depend':677 'deploy':583 'deprec':535 'design':12,380 'dev':726 'direct':56,255 'directori':220,337 'discuss':571 'document':575 'driven':734 'entri':377 'error':441,652 'esm':299 'execut':115,172,256,636,651 'extern':243,517 'featur':447,733 'fetch':348 'field':631 'file':67,334,402 'first':42 'flow':109,116,125,131,154,177,257,291,318,330,416,426,459,514,541,638 'flowchart':356 'four':188 'frontmatt':625 'full':491,622,682 'gemini':609 'generat':166,169,251,292,328,357,469,691 'github':223,339,342,484,568,581,666,717 'give':679 'goos':611 'graph':488,499 'grapherror':374 'group':201 'guid':586 'handl':75,653 'host':723 'html':496,500 'human':54 'ignor':272 'implement':444 'import':163,265,487,542,557 'includ':627 'independ':162 'init':368,502 'integr':353,512,566,664 'interact':495 'introspect':363 'issu':570 'juni':619 'key':301,379 'kiro':617 'languag':24 'level':160,191,521,533 'lineag':360,493 'list':241,365,508 'live':134,578 'local':221,284,558 'locat':208,244,315,528 'loop':120,261,648 'map':123,200,264,461,650 'mcpserver':628 'mermaid':355 'mismatch':435 'modul':300,302 'multi':30,588 'multi-ag':29 'multi-platform':587 'name':202,248 'namespac':204 'nest':544 'next':732 'node':515 'npm':547,552,706 'open':72 'option':246,675 'orchestr':129,133,165,184,211,293,326,352,468 'output':52,398,473,497,690 'overrid':560 'own':389 'page':582 'parallel':122,263,649 'pariti':626 'pars':279,305,312,319,344,467 'path':83,215,283,529 'peer':676 'per':68 'pipelin':33,277,362,387,486,545,637 'plain':400 'plan':173,252 'platform':589 'point':378 'prefix':553 'primit':240 'principl':13,381 'privat':480 'project':8,15,720 'provid':55 'publish':585,704 'pull':266,572 'read':332 'reads/writes':149 'recurs':96,350 'refer':216,438,478 'referenc':81 'remot':285,346 'repo':481 'request':573 'resolut':213,554 'resolv':281 'resolveerror':372 'resourc':193,197,198,268,522,534 'resum':660 'retry/skip/abort':654 'roo':614 'roo-cod':613 'rout':119,260,647 'run':634 'scaffold':369 'schema':146,236,311,429,458 'sdk':644 'sdkspawner':669 'search':549,551 'section':106,139,161,192,456 'self':722 'self-host':721 'separ':417 'servic':569,667 'singl':382 'site':576 'skill':71,77,80,88,97,130,185,194,219,230,247,269,282,321,336,347,403,413,422,450,477,532,548,556,584,630,692 'skill-level':531 'skill-skillfold-context' 'skill.md':66,92,327,333,401 'skillfold':2,7,14,21,58,60,364,367,498,501,503,505,507,550,633,708 'skillfold-context':1 'skillfold.local.yaml':561 'skillfold.yaml':729 'skills.atomic':214 'skills.composed':225 'sourc':383 'source-byronxlg' 'spawn':641,680 'spawner':642 'spec':471 'spec-compli':470 'split':99 'src/cli.ts':375 'src/compiler.ts':349 'src/config.ts':303 'src/errors.ts':370 'src/graph.ts':317 'src/init.ts':366 'src/list.ts':361 'src/orchestrator.ts':325 'src/remote.ts':341 'src/resolver.ts':331 'src/state.ts':309 'src/visualize.ts':354 'standard':65,73,397 'start-team.md':696 'state':141,145,155,195,207,233,235,271,289,310,322,391,427,457,565,662 'step':655 'strict':298 'structur':171,187 'sub':105,455,540 'sub-flow':539 'sub-sect':104,454 'subgraph':462 'suit':714 'system':314 'target':591,592,596,600,602,604,606,608,610,612,616,618,686 'team':108,137,176,196,273,425,599,689,703,727 'team.flow':254 'team.orchestrator':245 'test':711 'time':433,527,656 'token':485 'tool':43,683 'top':159,190,520 'top-level':158,189,519 'topic-agent-framework' 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-compiler' 'topic-multi-agent' 'topic-orchestrator' 'topic-pipeline' 'topic-skill-composition' 'topic-typescript' 'topic-yaml' 'topolog':393,423 'truth':385 'type':114,144,234,239,307,313,434 'typescript':297 'url':205,212,224,340,343,475 'url-bas':474 'use':670 'user':736 'v1.23.0':709 'valid':142,147,209,288,290,308,316,320,430,460,463,506,530 'via':483,639,728 'vision':35 'visual':489 'vitepress':574 'way':406 'when-claus':464 'wide':38 'windsurf':603 'wire':112 'work':19,449 'yaml':62,304","prices":[{"id":"cdeb8cf9-5716-44ee-9555-27712064c53d","listingId":"c9153abd-1271-4219-b2fd-4a1c9256a48c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"byronxlg","category":"skillfold","install_from":"skills.sh"},"createdAt":"2026-05-18T13:22:08.385Z"}],"sources":[{"listingId":"c9153abd-1271-4219-b2fd-4a1c9256a48c","source":"github","sourceId":"byronxlg/skillfold/skillfold-context","sourceUrl":"https://github.com/byronxlg/skillfold/tree/main/skills/skillfold-context","isPrimary":false,"firstSeenAt":"2026-05-18T13:22:08.385Z","lastSeenAt":"2026-05-18T19:14:27.877Z"}],"details":{"listingId":"c9153abd-1271-4219-b2fd-4a1c9256a48c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"byronxlg","slug":"skillfold-context","github":{"repo":"byronxlg/skillfold","stars":6,"topics":["agent-framework","agent-skills","ai-agents","claude-code","compiler","multi-agent","orchestrator","pipeline","skill-composition","typescript","yaml"],"license":"mit","html_url":"https://github.com/byronxlg/skillfold","pushed_at":"2026-05-02T04:13:05Z","description":"Configuration language and compiler for multi-agent AI pipelines. Compiles YAML config into standard SKILL.md files.","skill_md_sha":"45f1cf4ee1138a17b8a5ceed639916b8c75112a3","skill_md_path":"skills/skillfold-context/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/byronxlg/skillfold/tree/main/skills/skillfold-context"},"layout":"multi","source":"github","category":"skillfold","frontmatter":{"name":"skillfold-context","description":"Context about the Skillfold project, its architecture, and design principles."},"skills_sh_url":"https://skills.sh/byronxlg/skillfold/skillfold-context"},"updatedAt":"2026-05-18T19:14:27.877Z"}}