Para-Kit — Agent Structure Skill (v1.6.4)

Para-Kit is a colocated skill introduced in PARA Workspace v1.6.4 that gives AI agents immediate access to the workspace’s structural knowledge — without reading the entire Governing Kernel.

Why Para-Kit?

Before v1.6.4, agents needed to read multiple kernel files (invariants.md, heuristics.md, schema/*.md) to understand workspace rules. This consumed ~2000+ tokens and caused attention decay in long conversations.

Para-Kit solves this by packaging the most frequently needed references into a single SKILL.md file (~140 lines, ~600 tokens) that agents load on-demand via the trigger system.

When does it load?

Trigger Condition	Example
PARA structure questions	”Where do session logs go?“
project.md schema queries	”What fields does project.md have?”
CLI vs Workflow routing	”Should I use `./para install` or `/install`?”
Kernel quick reference	”What are the invariants?”

What’s Inside?

Para-Kit’s SKILL.md contains five sections:

Section 1: PARA Workspace Structure

The Four Pillars directory layout and the Standard Project Layout with all subdirectories explained:

Projects/    — Active work with deadlines or deliverables
Areas/       — Stable knowledge, SOPs, ongoing responsibilities
Resources/   — Reference materials, tools, templates (READ-ONLY for ai-agents/)
Archive/     — Cold storage for completed/cancelled items

It also covers Ecosystem Projects (v1.6.0+) — the standard vs ecosystem project types and cross-project @prefix references.

Section 2: project.md Schema (v1.6.3)

A complete field table for the YAML frontmatter contract:

Field	Type	Required	Description
`goal`	string	✅	Project objective
`status`	enum	✅	active / paused / done / archived
`strategy`	string/~	✅	Path to strategy doc
`roadmap`	path	✅	Path to roadmap plan
`active_plan`	string	❌	Current implementation plan
`agent.rules`	bool	✅	Has project-specific rules?
`agent.skills`	bool	✅	Has project-specific skills?
…	…	…	+ 10 more fields

It also points to colocated templates and test vectors for schema validation.

Section 3: Quick Reference Card — Kernel Governance

The most critical part — a one-liner summary of all 11 Invariants and 9 Heuristics:

Invariants (MUST — violation = MAJOR bump):

ID	Key Constraint
I1	Only 4 top-level dirs (PascalCase)
I2	backlog.md = authority, sprint = hot lane
I3	kebab-case naming only
I9	Resources/ai-agents/ = READ-ONLY
I10	Repo has no user data
I11	Output in preferences.language

Heuristics (SHOULD — violation = MINOR/PATCH):

ID	Key Guidance
H2	Context loading priority: project.md → rules → artifacts → areas
H6	Git only in repo/, not workspace root
H9	catalog.yml mandatory for governed libraries

Section 4: Selection Strategy

A decision matrix for when to use CLI (./para <cmd>) vs Workflows (/<cmd>):

CLI: Deterministic operations (install, update, status, archive)
Workflows: Collaboration & analysis (/brainstorm, /plan, /retro)

Section 5: On-demand References

Pointers to colocated files for deeper detail:

File	Content
`templates/project-md.md`	Full project.md template
`examples/project-schema-vectors.md`	Test vectors for validation

Skill Architecture

Para-Kit follows the colocated skill pattern introduced in v1.6.4:

.agent/skills/para-kit/
├── SKILL.md              # Main instruction file (~140 lines)
├── templates/            # project.md template
└── examples/             # Schema test vectors

All supporting files live inside the skill folder, enabling recursive sync during workspace updates — the agent always gets the latest version automatically.

Key Design Decisions

English-first: SKILL.md is written in English for maximum LLM compatibility, regardless of preferences.language.
One-liner summaries: Each invariant/heuristic is compressed to ~10 words. Full detail remains in Resources/ai-agents/kernel/.
No duplication: Para-Kit references kernel files rather than copying them. If an invariant changes, only the kernel source is updated.
Trigger-gated: Agents don’t read Para-Kit at session start — it loads only when a matching trigger fires.

→ Learn: Unified Agent Index — The trigger system that loads Para-Kit
→ Learn: The Kernel — Full kernel governance details
→ Learn: Central Gate — project.md as single source of truth