Agentic Package

Distribute instructions, not code. Let the LLM generate the implementation every time.

Agentic Package is a software distribution paradigm where only instructions and skill definitions are packaged — no executable code is included. The LLM generates the implementation from scratch each time, always leveraging its latest capabilities.

日本語版 README はこちら

Concept

Traditional software distribution ships compiled code or source code. Agentic Package ships instruction documents and skill definitions instead. This means:

• No code gets stale — the LLM generates fresh implementations using its current capabilities
• No dependency hell — instructions are plain Markdown and YAML files
• Evolves with AI — as LLMs improve, the same instructions yield better implementations
• Human-readable — the entire package can be reviewed and understood by anyone

Specification

See SPEC.md for the complete Agentic Framework Specification v0.1.0.

Standards Compliance

Area	Standard	Reference
Skill definitions	Agent Skills Specification	https://agentskills.io/specification
Instruction format	CLAUDE.md / AGENTS.md conventions	https://agents.md
Tool connections	Model Context Protocol (MCP)	https://modelcontextprotocol.io/specification
Agent communication	Agent2Agent Protocol (A2A)	https://a2a-protocol.org/latest/specification
Conditional rules	Claude Code Rules format	https://code.claude.com/docs/en/best-practices

What This Spec Defines

1. agent.yaml — Package manifest
2. No-Code Constraint — No executable code in packages
3. eval.yaml — Evaluation specification for LLM non-determinism
4. Loading Strategy — Progressive Disclosure rules
5. Capability Requirements — Abstract LLM capability levels

Package Structure

my-agent/
├── agent.yaml              # Required: Package manifest
├── instructions/            # Required: Instructions
│   ├── system.md           #   Required: Base instructions
│   ├── constraints.md      #   Optional: Guardrails
│   └── rules/              #   Optional: Conditional rules
│       └── *.md
├── skills/                  # Optional: Skills
│   └── skill-name/
│       ├── SKILL.md        #   Required: Skill definition
│       └── references/     #   Optional: Reference documents
│           └── *.md
├── examples/                # Optional: Few-shot examples
│   └── *.md
└── tests/                   # Recommended: Evaluation criteria
    └── eval.yaml

Quick Start

Using the Example Package

The examples/todo-app/ directory contains a complete example package that instructs an LLM to build a TODO application.

1. Clone this repository
2. Point your AI coding agent at the example package:

   "Read examples/todo-app/agent.yaml and follow the instructions to build the TODO app."
   

3. The LLM will read the manifest, load the instructions, and generate the full implementation

Creating Your Own Package

1. Create an agent.yaml manifest:

   apiVersion: agentic/v1
   kind: Agent
   metadata:
       name: my-agent
       description: "What this agent does"
       version: "1.0.0"

2. Write base instructions in instructions/system.md

3. Define skills in skills/<skill-name>/SKILL.md

4. Add evaluation criteria in tests/eval.yaml

5. Validate your package against the JSON schemas in schemas/

JSON Schemas

Validation schemas for the package format are provided in the schemas/ directory:

• schemas/agent-yaml.schema.json — Validates agent.yaml manifest files
• schemas/eval-yaml.schema.json — Validates eval.yaml evaluation files

Allowed File Types

Agentic Packages enforce a No-Code Constraint. Only these file types are permitted:

• .md — Instructions, skill definitions, reference documents
• .yaml / .yml — Manifests, evaluations, rule frontmatter
• .json — Schema definitions, sample data (non-executable)
• .txt — Plain text references

Executable files (.sh, .py, .ts, .js, Dockerfile, etc.) are prohibited.

License

MIT

Author

Arata Ouchi — Original SIN Architecture

• Website: https://osa.xyz
• X (Twitter): https://x.com/ouchiarata