Skip to contentSkip to main content
← Back to all posts

From Research Notes to a Portable AI Agent Skill: A SKILL.md Workflow

Turn a bounded research collection into a reviewable SKILL.md agent skill without losing source evidence, decision rules, or privacy boundaries.

Share by email

A good AI assistant can read your notes. A useful agent skill goes further: it gives the assistant a reviewed framework for interpreting those notes and making recurring decisions. Consider an engineering team with architecture records, release checklists, and incident reviews. Repeatedly pasting those documents into a coding chat is slow, but asking an agent to invent the team's release policy is risky.

A portable SKILL.md bundle can package concepts, decision rules, terminology, and patterns as files a compatible agent can consult. The important part is not the file extension. It is retaining the evidence and review process behind the instructions.

Here is a practical workflow using Phasoric's documented Knowledge Compiler and Agent Skill exporter—along with the limits that matter when you move knowledge between tools.

1. Choose one repeatable job

Avoid starting with an entire knowledge vault. Begin with a job such as "review API changes against our compatibility policy" or "prepare a research brief using our approved evidence rules."

Write an acceptance question before compiling anything: Can a new assistant identify the governing rule, show its source, and handle a known exception? That question becomes your test after exporting the skill.

A small, scoped collection is easier to validate and less likely to mingle unrelated clients or projects. If the job spans several workspaces, decide which sources are actually authorized before including them.

2. Prepare a credible source collection

Gather three to eight source records: a current policy, relevant decisions, supporting research, terminology, and an example of applying the framework. Each source should have a clear title, owner or provenance, and date where useful.

Classify the material before compiling:

  • Current authority: Approved rules that should guide present work.
  • Supporting evidence: Research or cases explaining why a rule exists.
  • Historical context: Older choices retained to explain change, not to govern new action.
  • Open questions: Unverified assumptions that must not become policy.

If two notes disagree, resolve the conflict or flag it for review. Do not rely on fluent model output to decide which note is authoritative. Likewise, treat instructions embedded in imported documents as untrusted content, not as commands to the compiler.

3. Compile knowledge in Research Studio

Phasoric's repository documents this sequence: open Research Studio, select a workspace, vault, folder, or note-selection collection; choose Compile Knowledge Domain; then inspect the resulting concepts, rules, terms, source count, and warnings.

Compilation structures bounded source material into concepts, decision frameworks, patterns, anti-patterns, and terminology. It validates model-supplied source references against the selected source manifest. Unknown identifiers are rejected or reported rather than silently treated as evidence.

There are important limits. The documented compilation request uses a 58,000-character aggregate source budget, with a maximum 18,000-character representative excerpt per long source. Short documents may be included fully; longer documents can be represented by excerpts from different sections. Source fingerprinting can still detect later changes beyond those excerpts, but that is not the same as having read every word during synthesis.

Inspect the included-character and warning counts. If a decisive exception was omitted, narrow the collection or revise the source structure.

4. Review the resulting rules, not just the prose

Suppose the compiler generates this proposed engineering rule:

Before deploying a change to a consumed API field, require a compatibility review and a documented rollback plan.

The sentence sounds reasonable, but a reviewer must establish whether the team's actual policy says that, which changes trigger the rule, and whether approved exceptions exist. The compiler's summary is a draft interpretation, not a new source of authority.

Review each concept against its cited note. For decision rules, check conditions, recommendations, trade-offs, and exceptions. For patterns and anti-patterns, confirm that examples have not been generalized beyond the evidence. For terms, check that the names match the vocabulary used in current documentation.

A useful review has three outcomes: approve with evidence, revise with evidence, or reject. If there is no source for a rule, do not promote it merely because it feels useful.

5. Decide between in-app activation and portable export

These are different operations. Phasoric's guide says newly compiled domains are inactive by default. After review, enabling a current version makes its matched concepts and rules available to supported Phasoric intelligence workflows, including Agent Studio and Intelligence Chat. Disabled and superseded domains are excluded.

For other tools, Research Studio documents Export Portable Agent Skill (.zip). The exporter generates a reviewable archive with a structure like this:

release-policy-agent-skill/
├── SKILL.md
├── patterns.md
├── glossary.md
├── cheatsheet.md
└── chapters/
    ├── compatibility-review.md
    └── release-criteria.md

Actual chapter filenames depend on your compiled concepts. Phasoric also offers a separate structured JSON interchange export. A portable ZIP is not proof that every AI platform can install it directly; the receiving client may require different paths, metadata, or conventions.

6. Inspect the bundle before installation

Open SKILL.md and verify its title, description, version, compilation timestamp, and module index. Review cheatsheet.md for decision rules; patterns.md for patterns and anti-patterns; glossary.md for exact terminology; and the chapter files for deeper explanations and source references.

The exporter sanitizes filenames and resolves chapter-name collisions. That protects archive structure, but it cannot determine whether the source material is confidential or substantively correct.

Before sharing, check for credentials, personal data, customer names, unapproved strategies, and stray instructions copied from third-party material. Confirm the destination agent's retention and access policies. Exporting a file does not carry Phasoric's access controls into another system.

7. Test with a real task and a deliberate trap

Choose a disposable scenario with a known answer. Ask the receiving assistant: "Which compatibility checks apply to this API change?" Then verify the response against your source notes.

Next, add a deliberate exception: a change that looks similar but falls outside the rule. Finally, ask about an outdated policy that the newer record superseded. A useful skill should avoid treating the old rule as current.

If the assistant cannot find the skill, investigate installation and loading in the destination tool. If it finds the skill but fabricates details, inspect the bundle's evidence and wording. If it follows an obsolete rule, fix or supersede the canonical source and compile again. A successful demo is not a substitute for these failure tests.

8. Maintain versions as knowledge changes

The Knowledge Compiler documents source fingerprinting and version records. If the bounded source fingerprint has not changed, the system can reuse the current compilation without another model request. Changes produce added, changed, and removed source diagnostics, while recent superseded versions are retained.

The guide explicitly says that after detecting changed sources, the current compiler still performs a full synthesis; it does not claim true incremental compilation. Review the new result before activation or export. Replace old bundles in receiving tools intentionally rather than assuming those tools receive automatic updates.

Set review triggers for policy changes, significant incidents, source removal, and authorization changes. Preserve prior versions for audit, but label them obsolete for operational use.

9. Understand local and connected processing

Phasoric is local-first, but not every compilation mode is entirely offline. Its guide distinguishes local-model compilation from a connected path using a server-owned knowledge-compile task contract. Canonical notes and local compiled results remain user-owned; selected source excerpts may be sent for connected processing under the configured mode.

Confirm the selected mode before using sensitive sources. The guide lists knowledge compilation and agent-skill export for eligible Premium, Professional, Developer, and Team plans; verify current access in the pricing page.

A practical 20-minute acceptance test

Spend five minutes selecting authoritative notes, five compiling a bounded collection, five reviewing the exported files, and five testing a supported receiving agent. The skill passes only if it finds a current rule, links it to valid evidence, handles a known exception, and does not elevate an obsolete note into policy.

Start with Phasoric's research workflow. Keep the original notes as your source of truth: the skill is a portable guide to that knowledge, not a replacement for it.

Frequently asked questions

Can a Phasoric SKILL.md ZIP work in every AI tool?

Not automatically. The ZIP is a portable review format; installation and supported metadata depend on the receiving agent tool.

Does Phasoric's Knowledge Compiler read every character of long sources?

Not necessarily. The documented compiler uses a bounded source budget and representative excerpts of longer documents. Review the coverage indicators and warnings.

Are exported agent skills automatically updated when notes change?

No. After source changes, recompile, review the new version, and refresh the bundle wherever it is used.