actor-profile
Create and maintain Actor entities — humans and AI agents that participate in the project. Use when adding a new collaborator (human or agent) to the project, updating their preferences/expertise, or querying who does what.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- actor-profile
- metadata
- { "processkit": { "id": "SKILL-actor-profile", "uses": [ { "skill": "event-log", "purpose": "Log events to keep the audit trail accurate after every write." }, { "skill": "index-management", "purpose": "Query existing entities and keep the SQLite index fresh after writes." }, { "skill": "id-management", "purpose": "Allocate unique entity identifiers via central ID generation." } ], "layer": 1, "created": 1775433600000, "version": "1.0.0", "category": "processkit", "provides": { "mcp_tools": [ "create_actor", "get_actor", "update_actor", "deactivate_actor", "list_actors" ], "templates": [ "actor-human", "actor-agent" ], "primitives": [ "Actor" ] }, "apiVersion": "processkit.projectious.work/v2" } }
- description
- Create and maintain Actor entities — humans and AI agents that participate in the project. Use when adding a new collaborator (human or agent) to the project, updating their preferences/expertise, or querying who does what.
02 资源文件 6
- 资产文件assets/actor-agent.yaml259 B
- 资产文件assets/actor-human.yaml294 B
- 参考文档mcp/mcp-config.json209 B
- 参考文档mcp/SERVER.md1.4 KB
- 脚本mcp/server.py10.7 KB
- 脚本scripts/.gitkeep—
03 SKILL.md 正文
Actor Profile Management
Intro
Actors are the entities that do things in the project — humans, AI agents, and services. This skill creates and maintains their profiles: name, type, contact, expertise, preferences, working style.
MCP server. This skill ships a self-contained MCP server at
mcp/server.py(PEP 723 script — requiresuvand Python ≥ 3.10 on PATH). Agent harnesses reach its tools by reading a single MCP config file at startup, so the contents ofmcp/mcp-config.jsonmust be merged into the harness's MCP config and placed at the harness-specific path before this skill is usable. If processkit was installed by an installer, that wiring is the installer's responsibility; if processkit was installed manually, the project owner must do it by hand.
Actor ID classes
Two accepted ID shapes for Actor entities (see context/schemas/actor.yaml
spec.role_actor_ids and DEC-20260421_2036-SoundIvy-two-class-actor-ids):
Role actor — ACTOR-<kebab-slug>
Stable identifier for a durable team role filled by successive agents or
people (e.g. ACTOR-product-manager, ACTOR-sr-architect). Current
allowlist (from spec.role_actor_ids in actor.yaml): assistant,
developer, jr-architect, jr-developer, jr-researcher,
product-manager,
sr-architect, sr-researcher. Use when the actor represents a role, not
an individual.
Identity actor — ACTOR-<YYYYMMDD_HHMM>-<WordPair>-<slug>
Canonical id-management format. Use for a specific individual, session, or
historical figure (owner, legacy backfill, session-specific agent). Example:
ACTOR-20260421_0144-ThriftyOtter-owner.
Adding a role to the allowlist
Requires amending spec.role_actor_ids in context/schemas/actor.yaml
(and its src/ mirror). This is a cross-cutting schema change — record a
DecisionRecord explaining why the new role is needed before making the
change. pk-doctor will ERROR on any ACTOR-<slug> ID whose slug is not in
the allowlist.
Overview
When to create an Actor
Create an Actor entity the first time a person or agent participates in a way the project needs to remember:
- Someone gets assigned a WorkItem → create their Actor if missing.
- An agent starts making decisions → create its Actor.
- A service account performs automated actions → create its Actor.
Do not promote every mention of a person into an Actor. Actors are for collaborators with ongoing involvement, not for every name that appears in a commit message.
Actor types
| type | Example |
|---|---|
human |
Project members, reviewers, stakeholders |
ai-agent |
Claude, Copilot, Aider, Cursor, custom MCP |
service |
GitHub Actions, CI bots, deploy pipelines |
Shape
---
apiVersion: processkit.projectious.work/v2
kind: Actor
metadata:
id: ACTOR-alice
created: 2026-04-06T00:00:00Z
spec:
type: human
name: "Alice Chen"
email: alice@example.com
expertise: [backend, databases, rust]
preferences:
commit_style: conventional
timezone: Europe/Berlin
active: true
---
Optional Markdown body — bio, context, working-style notes.
Workflow
- Pick an ID:
ACTOR-<short-name>where short-name is memorable and unique. - Set
type(human / ai-agent / service). - Fill in
name+ contact (email for humans; nothing for agents; service account identifier for services). - Record
expertiseas a tag list — used by assignment skills. - Write the Actor file to
context/actors/. - Log a
LogEntrywithevent_type: actor.created.
Gotchas
Agent-specific failure modes — provider-neutral pause-and-self-check items:
- Creating an Actor for every name mentioned in a commit or comment. Actors are for collaborators with ongoing involvement, not for every string that looks like a name. If the person doesn't have at least one upcoming WorkItem, decision, or Binding pointing at them, don't create the Actor yet.
- Putting personal or sensitive information in a public Actor file.
Personal context (relationship dynamics, private preferences,
personal contact info) belongs in
context/owner/private/...withprivacy: user-private, not in the Actor entity which defaults to project-visible. Check the privacy field on the entity before writing sensitive content. - Setting
typewrong.human/ai-agent/servicearen't cosmetic — other skills filter on type (e.g., to send a Slack ping only to humans, or to auto-promote service-account actions). Wrong type causes silent miscategorization downstream. - Updating an Actor when the relationship is what changed. If Alice's role on the project changed, that's a new Binding (or ending the old one), NOT an update to her Actor. The Actor is who she IS; the Binding is what she's DOING.
- Reusing a name as an ID for two distinct people. Two
collaborators named "Alice" need distinct Actor IDs
(
ACTOR-alice-pmvsACTOR-alice-eng). The ID is forever; the display name is mutable. Disambiguate at creation time, not later. - Hallucinating Actor IDs when other skills reference them. If
workitem-management is asked to assign a workitem to "Bob", look
up
ACTOR-bob(or allACTOR-bob-*) viaindex-managementfirst. Inventing an ID likeACTOR-bobwithout verifying creates a dangling reference that breaks at the next index validation. - Forgetting to log
actor.created. Useevent-logafter every Actor creation. The audit trail tracks "who joined when", and skipping the log makes "when did Alice start working on this?" unanswerable.
Full reference
Fields
| Field | Type | Notes |
|---|---|---|
type |
enum | human / ai-agent / service |
name |
string | Display name. For agents: model name + version. |
email |
string | Optional. Human actors only. |
handle |
string | Optional. GitHub handle, Slack user, etc. |
expertise |
list[string] | Tags used by assignment suggestions. |
roles |
list[string] | Role IDs. For scoped roles prefer a Binding over this. |
preferences |
map | Free-form. See conventional keys below. |
active |
bool | false = profile preserved but no new work assigned. |
joined_at |
datetime | When they became part of the project. |
left_at |
datetime | When they stopped (sets active: false). |
Conventional preference keys
commit_style:conventional/freeformtimezone: IANA namereview_style:strict/pragmatic/lightcommunication:async/sync/mixedlanguages: human languages for communication
These are conventions, not enforced. Projects may add any preferences they like.
Scoped roles: use a Binding, not the roles field
spec.roles is a shortcut for "Alice is a developer" when that's true
everywhere in the project. If "Alice is the tech lead for Project X but a
regular developer everywhere else", use a Binding entity instead:
kind: Binding
spec:
type: role-assignment
subject: ACTOR-alice
target: ROLE-tech-lead
scope: SCOPE-project-x
See skills/binding-management for details.
Deactivation, not deletion
When an actor leaves the project, set active: false and left_at. Do not
delete the file — historical LogEntries and Bindings reference it. Queries
for "current team" should filter by active: true.
Privacy considerations
Actor files are checked into git and visible to everyone with repo access. Do not put sensitive contact info (phone, home address) in Actor files. Keep email optional — agents and services do not need one.
04 同仓库更多 Skills
standard-ui-design
暂无简介
standard-agent-use
Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.
standard-agent-building
暂无简介
skill-management
Manage Skill package manifests as v1 ontology entities.
schema-management
Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.
proposition-management
Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.